XTargets Matlab 2 Matlab
  -------------------------------
  
  Package     -     Distributed Computing / Multitasking toolbox for Matlab
  
  Author      -     Brad Phelan
  
  WebSite     -     http://xtargets.com
  
  Copyright   -     2005 Brad Phelan
  
  License     -     LGPL
  
  Summary
  -------
      The XTargets Matlab 2 Matlab Toolbox allows you to create a grid of
      matlab computing resources. There are three steps involved. 
  
      (1) Create the grid engine server which allows registration,
          querying and acquisition of remote matlab resources.
  
      (2) Computing resources can register ther availibility with the grid 
          engine.
  
      (3) The client machine can request handles to remote matlab computing
          resources from the grid engine.
  
      (4) The client machines uses the remote computing resources
  
  
  Usage
  -------
  
      (1) Create the Grid Engine
      --------------------------
  
      At the matlab prompt type
  
      >> x = xtargets_m2m_start_grid
  
      This will start the grid server on the default port of 1099. You can
      pass a port parameter to the function if you wish. If you wish to start
      the grid without matlab the java static method is ...
  
      com.xtargets.matlab.multi.rmi.GridManagerImpl.startGrid()
  
      or 
  
      com.xtargets.matlab.multi.rmi.GridManagerImpl.startGrid(int port)
 
      You can shutdown the grid by calling
 
      >> x.shutdown
  
      (2) Register a computing resource with the grid engine
      -------------------------------------------------------
  
      At the matlab prompt type
  
          >> lease_manager = xtargets_m2m_export_matlab(name, hostname, port)
  
      where 
          name     - is the name you wish to assign to this resource
                     on the grid
          hostname - is the host where the grid engine resides
          port     - is the tcp-ip port on the host where the grid engine
                     resides.
      
      You can shutdown the lease manager by calling
 
          >> lease_manager.shutdown
  
      (3) Acquire a remote matlab computing resource
      ----------------------------------------------
  
      At the matlab prompt type
  
          >> m = xtargets_m2m_client(hostname, port, lock)
  
      where 
          hostname  -   is the name of the host where the grid engine resides
          port      -   port is the tcp-ip port on the host where the grid
                        engine resides.
          lock      -   true - if you want exclusive access to this resource
 
      You can release the remote matlab resource by calling
 
          >> delete(m);
  
      (4) Use the remote computing resource
      -------------------------------------
  
          >> m = xtargets_m2m_client('localhost', 1099, true);
          >> x = feval(m, 'sum', 1:10)
          x =
              55
  
      This however is not very usefull because the client blocks until
      the server returns the answer. What we want to do is be able to
      do usefull work or ping off requests to other servers while this
      server is chewing on it's answer. You do this with the following
      pattern
  
          >> ticket = as_feval(m, 1,  'sum', 1:10);
          >> x = ticket()
          x =
              55
  
      Note the parameter 1 tells as_feval to collect 1 argument from the
      remote function. If you wish to collect more than one argument you need
      to tell as_feval how many you want.
              
      Here you are returned a ticket when you call as_feval. The ticket
      is a function handle which you can invoke to collect the result. If
      the result is not ready yet then the function blocks. It could be 
      used in the following scenario
  
          % Create connections to remote servers
          c(1) = xtargets_m2m_client('machine1',1099, true);
          c(2) = xtargets_m2m_client('machine2',1099, true);        
          c(3) = xtargets_m2m_client('machine3',1099, true);        
  
          % Spawn the instructions to the remote machines
          for i = 1:3
              ticket{i} = as_feval(c(i),1,'sum', rand(100));
          end
  
          % Collect the answers.
          for i = 1:3
              disp(ticket());
          end
  
      The transport mechanism involves serializing and deserializing matlab
      data using mxSerialize and mxDeserialize. These two mx functions live in
      libmx.dll and are *undocumented* by the Mathworks so don't go bugging
      them for support if you want to find out more about how they work.
  
      The transport is handled by java network io and java manages all
      the threading and handshaking between client and server. The server
      is not blocked whilst waiting to receive commands. The java threads
      use ( once more undocumented ) java matlab apis in jmi.jar to call
      into matlab when it is ready. 
  
      There is very little matlab code involved. A simple protocol for
      packaging up function call names and function call arguments into
      a cell array has be devised and you can look to the code for details
      on it.
  
  Applications
  ------------
      -   Clustered computing ( Coarse grain problems )
      -   Clustered Simulink simulations 
      -   Remote testing of matlab toolboxes
                
  Installation
  ------------
  
     Add the directory this file is in to your matlab path. 
     Add the following directory to the matlab classpath.txt
     
     INSTDIR/java/src/RemoteMatlab 
  
     The toolbox does not work if you add the classes to the
     dynamic java path using javaaddpath.
  
  From The Start Menu
  -------------------
     On the Matlab Start Menu there is added an entry for the
     Matlab 2 Matlab toolbox. From there you can access this
     document, start the grid, export matlab resources and
     acquire matlab resource.
  
     The client gui places a variable in the base workspace
     which you can then use for feval remote operation as
     per the instructions above.
    
  
  To Do
  -------
  
  Security
  --------
     At the moment I am installing a policy file which
     allows all and anything as I don't really have much
     familiarity with the Java security model. It would
     be good to lock down the computing model to trusted
     computers.
 
  Testing
  -------
 
  Start one session of matlab and run 
 
    xtargets_m2m_test_server
 
  Run another session of matlab
 
    xtargets_m2m_test_client
 
  For JUnit java based testing see the java src package 
 
    com.xtargets.matlab.multi.test
  
  
   Copyright (c) 2005 Brad Phelan as LGPL
   http://xtargets.com
   See license.txt for LGPL terms