sleigh                  package:nws                  R Documentation

_C_l_a_s_s "_s_l_e_i_g_h"

_D_e_s_c_r_i_p_t_i_o_n:

     Represents a collection of R processes used to execute tasks.

     The sleigh allows R functions to be executed in parallel using the
     'eachElem' and  'eachWorker' methods.

     The sleigh workers are started when the sleigh object is
     constructed.  When tasks are submitted to the sleigh, using the
     'eachWorker' and 'eachElem' methods, the workers execute the tasks
     and return the results.  When the 'stopSleigh' method is called,
     the workers are stopped.

     A given R program can create multiple sleigh objects, each of
     which will have its own set of workers.  This can be useful if
     tasks have different requirements.  For example, you could create
     a Linux sleigh and a Windows sleigh, and submit Windows-specific
     tasks only to your Windows sleigh.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

     Objects can be created by calls of the form 
      'sleigh(...)' 
      or 
      'new("sleigh",...)'
      where '...' can be one or more of the following named arguments:

     '_n_o_d_e_L_i_s_t': a list of hosts on which workers will be created. 
          This argument is ignored when 'launch='local''.  The default
          value is 'c('localhost', 'localhost', 'localhost')'.

     '_w_o_r_k_e_r_C_o_u_n_t': number of workers that will be created. When
          'launch='local'', the default value is 3. If 'nodeList' is
          provided, the actual set of workers is determined using
          'rep(nodeList, length=workerCount)', which effectively does a
          round-robin scheduling on the nodes in 'nodeList'. For
          example, if 'nodeList=c("n1","n2", "n2", "n3","n3","n3")' and
          'workerCount=20', there will be four workers on node n1,
          seven on node n2, and nine on node n3.

     '_l_a_u_n_c_h': method to launch remote workers.  This can be set to the
          strings ''local'' (the default) or ''web'', or to a function
          object.  

          The function is called once for each worker listed in
          'nodeList'.  It  is passed two arguments: a name from
          'nodeList', and an  environment object that was constructed
          by merging 'defaultSleighOptions'  with the arguments that
          were passed to the sleigh constructor.  The  function should
          return a character vector, where the first element is the 
          command to execute, and the subsequent elements are the
          command arguments.   For example, the function could return
          the vector  'c('ssh', '-f', 'host')', where ''host'' is the
          first  argument to the launch function.  This  isn't the
          complete command to be executed; it's the 'remote execution' 
          portion of the command. The sleigh constructor will add the
          rest of the command based on the 'scriptExec' argument.  Note
          that the command is expected to return after launching the
          worker.  That is why the ssh -f option is used in the
          example.


     '_s_e_r_v_e_r_I_n_f_o': an object of type 'serverInfo' or
          'managedServerInfo' that describes the netWorkSpaces server.
          Default is the return variable of 'getServer'.

     '_s_c_r_i_p_t_E_x_e_c': command to execute worker script.  Default uses
          'scriptcmd' function on Windows, and uses 'envcmd' function
          on  other platforms.

     '_s_c_r_i_p_t_D_i_r': location of the sleigh worker script. Default is the 
          bin directory under the nws package location. If library
          cannot be found, then use current working directory. 

     '_s_c_r_i_p_t_N_a_m_e': worker script file name. Default is 
          'RNWSSleighWorker.py' on Windows, and 'RNWSSleighWorker.sh'
          on other platforms.

     '_w_o_r_k_i_n_g_D_i_r': worker's working directory. Default is  master's
          current working directory.

     '_l_o_g_D_i_r': location where log files will be stored. Default is 
          'NULL'.

     '_o_u_t_f_i_l_e': remote workers' standard errors will be redirected to 
          this file. Default is 'NULL'.

     '_w_s_N_a_m_e_T_e_m_p_l_a_t_e': template name to create sleigh workspace. 
           Default is ''sleigh_ride_%010d''.

     '_u_s_e_r': user name used for remote execution.  Default is  'NULL'.

     '_v_e_r_b_o_s_e': a logical value indicating whether to print out debug
          messages. Default is 'FALSE'.

     '_r_n_g_T_y_p_e': a string indicating the type of random number generator
          to initialize the workers with.  Defaults to ''legacy'',
          which does a limited initialization.  If the 'sprngNWS'
          package is available, the following options are available:

          '_s_p_r_n_g_L_F_G': Modified Lagged Fibonacci Generator

          '_s_p_r_n_g_L_C_G': 48 Bit Linear Congruential Generator with Prime
               Addend

          '_s_p_r_n_g_L_C_G_6_4': 64 Bit Linear Congruential Generator with Prime
               Addend

          '_s_p_r_n_g_C_M_R_G': Combined Multiple Recursive Generator

          '_s_p_r_n_g_M_L_F_G': Multiplicative Lagged Fibonacci Generator

          For more information on these, see spring documentation at
          http://sprng.cs.fsu.edu/

     '_r_n_g_S_e_e_d': a numeric value that will be passed to the random
          number generator initialization function.  It is not used by
          the ''legacy'' type.

     '_f_i_x_e_d_a_r_g_s_S_i_z_e': a numeric value indicating the minimum size, in
          bytes, and object must be before large object optimization
          will be done.  The correct value of this will depend on
          network speed and latency.

_M_e_t_h_o_d_s:


     _i_n_i_t_i_a_l_i_z_e 'signature(.Object = "sleigh")': sleigh class
          constructor.

     _e_a_c_h_E_l_e_m 'signature(.Object = "sleigh")': evaluate the given
          function with multiple argument sets using the workers in
          sleigh.

     _e_a_c_h_W_o_r_k_e_r 'signature(.Object = "sleigh")': evaluate the given
          function exactly once for each worker in sleigh.

     _r_a_n_k_C_o_u_n_t 'signature(.Object = "sleigh")': get sleigh's rankCount.

     _s_t_a_t_u_s 'signature(.Object = "sleigh")': return the status of the
          sleigh.

     _s_t_o_p_S_l_e_i_g_h 'signature(.Object = "sleigh")': shut down workers and
          remove sleigh workspace.

     _w_o_r_k_e_r_C_o_u_n_t 'signature(.Object = "sleigh")': get number of workers
          started in sleigh.

_D_e_t_a_i_l_s:

     There are six different standard launch types (''local'',
     'sshcmd',  'rshcmd', 'lsfcmd', 'sshforwardcmd', and ''web'') to 
     tailor the client's working environment.  This is done by setting
     launch variable to a function ('sshcmd', 'rshcmd', 
     'sshforwardcmd' or 'lsfcmd') or a string ('local' and 'web').  See
     the examples section.

_N_o_t_e:

     The constructor still supports the 'nwsHost' and 'nwsPort'
     arguements, but as of release 2.0, they are deprecated and will be
     removed in 4.0. The legacy descriptions are:

     'nwsHost': host name of the netWorkSpaces server. Default is the
     machine where sleigh starts up.

     'nwsPort': port number of the netWorkSpaces server. Default is 
     8765.

     If the user specifies both one or more deprecated options and a
     serverInfo object, the deprecated option(s) will be ignored.

_E_x_a_m_p_l_e_s:

     ## Not run: 
     # Default option: create three sleigh workers on local host:
     s <- sleigh()
     # which is equivalent to:
     s <- sleigh(launch='local')

     # Create sleigh workers on multiple machines using SSH:
     s <- sleigh(nodeList=c('n1', 'n2', 'n3'), launch=sshcmd)

     # Use the LSF bsub command to launch ten workers:
     s <- sleigh(nodeList=rep('fake', 10), launch=lsfcmd)

     # Use web launch:
     s <- sleigh(launch='web')
     ## End(Not run)

