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. #
