function nproc_available = cosmo_parallel_get_nproc_available(varargin)
% get number of processes available from Matlab parallel processing pool
%
% nproc=cosmo_parallel_get_nproc_available()
%
% Input:
% 'nproc',nproc_wanted Number of desired processes (optional)
% If not provided, then the number of
% available cores is returned.
% Use 'nproc',inf to get as many
% cores as there available.
% 'nproc_available_query_func',f Function handle to determine how many
% processes are available. This function
% is intended for use by developers only;
% by default it selects the appropriate
% function based on the platform (Octave,
% Matlab <= 2013b, or Matlab > 2013b)
%
% Output:
% nproc_available Number of available parallel processes.
% - On Matlab: this requires the parallel
% computing toolbox
% - On Octave: this requires the parallel
% toolbox
% If the required toolbox is not
% available, then nproc_available=1.
% If there are nproc_available
% processes available and
% nproc_available<nproc_wanted
% then nproc=nproc_available is returned.
%
% Notes:
% - If no parallel processing pool has been started, then this function
% will try to start one (with as many parallel processes as possible)
% before counting the number of processes available.
% - If a parallel processing pool has already been started, then this
% function returns the number of processes available it that pool. This
% function *does not* close an existing pool and open a new one. This
% means that if a user has started a pool with M processes on a machine
% with N processes available (i.e. a pool has started with fewer
% processes than available), then this function will return M (and not
% N if M<N). If you need a fresh pool with
%
% See also: parcellfun, matlabpool
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
defaults = struct();
opt = cosmo_structjoin(defaults, varargin{:});
check_inputs(opt);
[has_nproc_wanted, nproc_wanted] = get_nproc_wanted(opt);
if has_nproc_wanted && nproc_wanted <= 1
nproc_available = 1;
return
end
max_nproc_available_query_func = get_max_nproc_available_func(opt);
[max_nproc_available, msg] = max_nproc_available_query_func();
if ~has_nproc_wanted
nproc_available = max_nproc_available;
return
end
% getting here it means opt.nproc>1, i.e. the user asked for more than
%
nproc_wanted = opt.nproc;
nproc_available = max_nproc_available;
if nproc_wanted > max_nproc_available
full_msg = sprintf(['''nproc''=%d requested, but %s. '...
'Using ''nproc''=%d'], ...
nproc_wanted, msg, nproc_available);
if ~isinf(nproc_wanted)
% do not show warning if nproc_wanted is infinity
cosmo_warning(full_msg);
end
end
if nproc_wanted < nproc_available
nproc_available = nproc_wanted;
end
function [has_nproc_wanted, nproc_wanted] = get_nproc_wanted(opt)
nproc_wanted = NaN;
has_nproc_wanted = isfield(opt, 'nproc');
if has_nproc_wanted
nproc_wanted = opt.nproc;
end
function func = get_max_nproc_available_func(opt)
override_key = 'nproc_available_query_func';
if isfield(opt, override_key)
func = opt.(override_key);
return
end
if cosmo_wtf('is_matlab')
v_num = cosmo_wtf('version_number');
% Matlab 2013b is version 8.2
if v_num(1) > 8
is_matlab_ge_2013b = 1;
else
is_matlab_ge_2013b = v_num(1) == 8 && v_num(2) >= 2;
end
if is_matlab_ge_2013b
func = @matlab_get_max_nproc_available_ge2013b;
else
func = @matlab_get_max_nproc_available_lt2013b;
end
elseif cosmo_wtf('is_octave')
func = @octave_get_max_nproc_available;
else
assert(false, 'this should not happen');
end
function check_inputs(opt)
if isfield(opt, 'nproc')
nproc = opt.nproc;
if ~(isnumeric(nproc) && ...
isscalar(nproc) && ...
nproc >= 1 && ...
round(nproc) == nproc)
error('nproc must be a positive scalar');
end
end
function [nproc_available, msg] = matlab_get_max_nproc_available_lt2013b()
nproc_available = 1;
msg = check_java_and_funcs({'matlabpool'});
if ~isempty(msg)
return
end
pool_func = @matlabpool;
open_pool_func = pool_func;
query_pool_func = @()pool_func('size');
% get number of processes
try
nproc_available = query_pool_func();
pool_is_open = nproc_available > 0;
if ~pool_is_open
% try to open pool
open_pool_func();
nproc_available = query_pool_func();
end
catch
msg = lasterr();
return
end
% ensure nproc_available>=1
nproc_available = max(nproc_available, 1);
function [nproc_available, msg] = matlab_get_max_nproc_available_ge2013b()
msg = '';
nproc_available = 1;
matlab_parallel_functions = {'gcp', 'parpool'};
if ~(usejava('jvm') && ...
platform_has_functions(matlab_parallel_functions))
msg = 'java or parallel functions not available';
return
end
try
pool = gcp();
if isempty(pool)
msg = ['Parallel toolbox is available, but '...
'unable to open pool'];
return
end
catch
msg = lasterr();
return
end
nproc_available = pool.NumWorkers();
function msg = check_java_and_funcs(function_names)
msg = '';
if ~(usejava('jvm') && ...
platform_has_functions(function_names))
msg = 'java or parallel functions not available';
return
end
function [nproc_available, msg] = octave_get_max_nproc_available
msg = '';
nproc_available = 1;
if ~cosmo_check_external('octave_pkg_parallel', false)
msg = 'parallel toolbox is not available';
return
end
nproc_available = nproc('overridable');
function tf = platform_has_functions(function_names)
tf = all(cellfun(@(x)~isempty(which(x)), function_names));
