added 'run_javaaddpath' option for users making use of globals. See d…

…ocs.

ParforProgressStarter2.m

@@ -1,16 +1,26 @@
-function ppm = ParforProgressStarter2(s, n, percentage, do_debug)
+function ppm = ParforProgressStarter2(s, n, percentage, do_debug, run_javaaddpath)
 % Starter function for parfor progress-monitor, that will automatically 
 % choose between a text or a GUI progress monitor. You can use this 
 % progress-monitor in both for and parfor loops.
 %
 % ParforProgressStarter2 is the successor of ParforProgressStarter - it is 
 % roughly 12 times more performant during GUI mode!
 % 
-% you should use it like this:
-% 
+% You should use ParforProgressStarter2 like this:
+%
+%%%%%%%%%%%%%% Begin ParforProgressStarter2 suggested usage %%%%%%%%%%%%%%%
+%
+%   % how many iterations of the for loop do we expect?
 %   N = 1000;
+%   % how often should the monitor update it's progress?
+%   percentage_update = 0.1;
+%   % show debugging information.
+%   do_debug = 1;
+%   % by default we always run 'javaaddpath'. Set this to 0 if you are 
+%   % making use of globals.
+%   run_javaaddpath = 1; 
 %   try % Initialization
-%       ppm = ParforProgressStarter2('test', N, 0.1);
+%       ppm = ParforProgressStarter2('test', N, percentage_update, do_debug, run_javaaddpath);
 %   catch me % make sure "ParforProgressStarter2" didn't get moved to a different directory
 %       if strcmp(me.message, 'Undefined function or method ''ParforProgressStarter2'' for input arguments of type ''char''.')
 %           error('ParforProgressStarter2 not in path.');
@@ -34,13 +44,14 @@
 %   catch me %#ok<NASGU>
 %   end
 %
+%%%%%%%%%%%%%% End ParforProgressStarter2 suggested usage %%%%%%%%%%%%%%%%%
 % 
 % Copyright (c) 2010-2014, Andreas Kotowicz
 %
     %%
 
     if nargin < 2
-        disp('usage: ppm = ParforProgressStarter2( text, number_runs, update_percentage)');
+        disp('usage: ppm = ParforProgressStarter2( text, number_runs, update_percentage, do_debug, run_javaaddpath )');
         ppm = [];
         return;
     end
@@ -52,6 +63,10 @@
     if nargin < 4
         do_debug = 0;
     end
+
+    if nargin < 5
+        run_javaaddpath = 1;
+    end
 
     %% determine whether java and awt are available
     java_enabled = 1;
@@ -94,15 +109,14 @@
     %% add directory to javapath and path
     a = which(mfilename);
     dir_to_add = fileparts(a);
-    server_class_loaded = exist('ParforProgressServer2', 'class');
 
     if pool_slaves > 0
-        if java_enabled == 1 %&& ~server_class_loaded
+        if java_enabled == 1 && run_javaaddpath == 1
             pctRunOnAll(['javaaddpath({''' dir_to_add '''})']);
         end
         pctRunOnAll(['addpath(''' dir_to_add ''')']);
     else
-        if java_enabled == 1 %&& ~server_class_loaded
+        if java_enabled == 1 && run_javaaddpath == 1
             javaaddpath({dir_to_add});
         end
         addpath(dir_to_add);

ParforProgressStressTest2.m

@@ -1,21 +1,31 @@
-function ParforProgressStressTest2(N)
+function ParforProgressStressTest2(N, run_javaaddpath)
 % Stress test for 'ParforProgressStarter2'. In case of timeouts, you can
 % use this function to determine how many simultaneous connections your
 % computer can handle, and adjust the ppm.increment() call accordingly.
 %
 % Copyright (c) 2010-2014, Andreas Kotowicz
 %
 %%
+
+    if nargin < 2
+        % by default we always run 'javaaddpath'. Set this to 0 if you are 
+        % making use of globals.
+        run_javaaddpath = 1;
+    end
+
     if nargin < 1
+        % how many iterations of the for loop do we run?
         N = 10000;
     end
 
-    do_debug = 1;
-
     %% initialize ParforProgress monitor
-
+
+    % how often should the monitor update it's progress?
+    percentage_update = 0.1;
+    % show debugging information.
+    do_debug = 1;
     try % Initialization
-        ppm = ParforProgressStarter2('test task - ParforProgressStarter2', N, 0.1, do_debug);
+        ppm = ParforProgressStarter2('test task - ParforProgressStarter2', N, percentage_update, do_debug, run_javaaddpath);
     catch me % make sure "ParforProgressStarter2" didn't get moved to a different directory
         if strcmp(me.message, 'Undefined function or method ''ParforProgressStarter2'' for input arguments of type ''char''.')
             error('ParforProgressStarter2 not in path.');

README.md

@@ -9,7 +9,45 @@ This progress monitor comes with a nice wrapper `ParforProgressStarter2.m` which
 * clone this directory 
 * add directory to matlab path
 
-## C) HOW TO USE
+## C) HOW TO USE (no globals)
 
 see `ParforProgressStressTest2.m` or `ParforProgressStarter2.m`
 
+
+## D) HOW TO USE (with globals)
+
+### Matlab 2012b and later:
+- create `javaclasspath.txt` file in your preference directory.
+- add path to `ParforProgressStarter2` to this file.
+
+On Linux this translates to:
+```
+$ cd .matlab/R2013a
+$ echo "/path/to/matlab-ParforProgress2" > javaclasspath.txt
+```
+
+Next, startup Matlab and call `ParforProgressStarter2`, but do not run `javaddpath`:
+
+```
+ >> run_javaaddpath = 0;
+ >> ParforProgressStressTest2(10000, run_javaaddpath)
+```
+
+
+### Matlab 2012a and earlier:
+
+Unfortunately Matlab 2012a and earlier versions of Matlab do not support customized
+`javaclasspath.txt` files, instead, you need to edit the `classpath.txt` file that is
+part of the Matlab installation. You might need administrator / superuser privileges to 
+edit this file. Here's how you can locate it:
+
+```
+>> which classpath.txt -all
+/share/pkgs/MATLAB/R2012a/toolbox/local/classpath.txt
+>> edit classpath.txt 
+```
+
+
+See http://www.mathworks.com/help/matlab/matlab_external/bringing-java-classes-and-methods-into-matlab-workspace.html for further information regarding `javaclasspath`.
+
+