slang-pvm 0.1.5-12.1 / usr / share / slsh / local-packages / help / pvm.hlp

pvm_send_obj

 SYNOPSIS
  Pack and send data objects

 USAGE
  pvm_send (Int_Type tid, Int_Type msgid, object [,...])

 DESCRIPTION
  This function is much like `pvm_psend' except that it
  sends additional type information with each object. Using
  this function paired with `pvm_recv_obj' simplifies
  sending aggregate data objects such as structures and removes
  the need for the receiver to specify datatypes explicitly.

 EXAMPLE

  To send a S-Lang structure to another process:

  variable obj = struct {name, x, y, data};
  ...
  pvm_send_obj (tid, msgid, obj);


 SEE ALSO
  pvm_recv_obj, pvm_psend, pvm_unpack

--------------------------------------------------------------

pvm_recv_obj

 SYNOPSIS
  Receive data objects from `pvm_send_obj'

 USAGE
  obj = pvm_recv_obj ()

 DESCRIPTION
  This function receives an object sent by `pvm_send_obj'
  and returns a slang object of the same type that was sent.
  It simplifies sending aggregate data types such as structures.

 EXAMPLE

  To receive a S-Lang object sent by another process
  via `pvm_send_obj':

  obj = pvm_recv_obj ();


 SEE ALSO
  pvm_send_obj, pvm_psend, pvm_unpack

--------------------------------------------------------------

pvm_config

 SYNOPSIS
  Returns information about the present virtual machine configuration

 USAGE
  Struct_Type = pvm_config ()

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  h = pvm_config ();


 SEE ALSO
  pvm_kill

--------------------------------------------------------------

pvm_kill

 SYNOPSIS
  Terminates a specified PVM process

 USAGE
  pvm_kill (Int_Type tid)

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  pvm_kill (tid);


 SEE ALSO
  pvm_config

--------------------------------------------------------------

pvm_initsend

 SYNOPSIS
  Clear default send buffer and specify message encoding

 USAGE
  bufid = pvm_initsend (Int_Type encoding)

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  bufid = pvm_initsend (PvmDataDefault);


 SEE ALSO
  pvm_send

--------------------------------------------------------------

pvm_pack

 SYNOPSIS
  Pack the active message buffer with arrays of prescribed data type

 USAGE
  pvm_pack (object)

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  pvm_pack (x);


 SEE ALSO
  pvm_unpack

--------------------------------------------------------------

pvm_send

 SYNOPSIS
  Immediately sends the data in the active message buffer

 USAGE
  pvm_send (Int_Type, tid, Int_Type msgid)

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  pvm_send (tid, msgid);


 SEE ALSO
  pvm_recv

--------------------------------------------------------------

pvm_recv

 SYNOPSIS
  Receive a message

 USAGE
  bufid = pvm_recv (Int_Type tid, Int_Type msgtag)

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

   bufid = pvm_recv (tid, msgtag);


 SEE ALSO
  pvm_send

--------------------------------------------------------------

pvm_unpack

 SYNOPSIS
  Unpack the active message buffer into arrays of prescribed data type

 USAGE
  item = pvm_unpack (Int_Type type_id, Int_Type num)

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  item = pvm_unpack (type, num);


 SEE ALSO
  pvm_pack

--------------------------------------------------------------

pvm_psend

 SYNOPSIS
  Pack and send data

 USAGE
  pvm_psend (Int_Type tid, Int_Type msgid, object [,...])

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  pvm_psend (tid, msgid, data);


 NOTES
  Unlike the `pvm_send' function in the PVM library, this function
  does not operate asynchronously.

 SEE ALSO
  pvm_send, pvm_initsend, pvm_pack, pvm_recv

--------------------------------------------------------------

pvm_addhosts

 SYNOPSIS
  Add one or more hosts to the PVM server

 USAGE
  Int_Type[] = pvm_addhosts (String_Type[] hosts)

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  tids = pvm_addhosts (["vex", "verus", "aluche"]);


 SEE ALSO
  pvm_addhosts, pvm_config, pvm_delhosts

--------------------------------------------------------------

pvm_delhosts

 SYNOPSIS
  Delete one or more hosts from the PVM server

 USAGE
  pvm_delhosts (String_Type[] hosts)

 DESCRIPTION
  See the PVM documentation.

 EXAMPLE

  pvm_delhosts (["vex", "verus"]);


 SEE ALSO
  pvm_delhosts, pvm_config, pvm_kill

--------------------------------------------------------------

pvm_ms_kill

 SYNOPSIS
  Send a "task complete" message to a specific task

 USAGE
  pvm_ms_kill (Int_Type mtid, Int_Type stid)

 DESCRIPTION
  This function may be used to send a "task complete" message
  to a specific PVM process.  The first argument gives
  the task identifier of the destination process.  The second
  argument gives the task identifier of the sending process.

 EXAMPLE

  tid = pvm_mytid ();
  ptid = pvm_parent ();
  pvm_ms_kill (ptid, tid);


 SEE ALSO
  pvm_ms_slave_exit

--------------------------------------------------------------

pvm_ms_set_num_processes_per_host

 SYNOPSIS
  Set the maximum number of simultaneous processes per host

 USAGE
  pvm_ms_set_num_processes_per_host (Int_Type num_processes)

 DESCRIPTION
  This function is used to set the maximum number of simultaneous
  processes per host.  The master process normally runs as many
  simultaneous processes as possible;  by setting the maximum
  number of simultaneous processes per host, one can limit the
  processing load per host.

 EXAMPLE

  pvm_ms_set_num_processes_per_host (2);


 SEE ALSO
  pvm_ms_run_master

--------------------------------------------------------------

pvm_ms_set_debug

 SYNOPSIS
  Set the debug flag

 USAGE
  pvm_ms_set_debug (Int_Type debug)

 DESCRIPTION
  This function may be used to control whether debugging
  information is printed out during execution.  Debugging
  information is printed if the flag is non-zero.

 EXAMPLE

  pvm_ms_set_debug (1);


 SEE ALSO
  pvm_ms_set_num_processes_per_host

--------------------------------------------------------------

pvm_ms_slave_exit

 SYNOPSIS
  Cause a normal exit of a slave process from the PVM

 USAGE
  pvm_ms_slave_exit (Int_Type exit_status)

 DESCRIPTION
  To exit the PVM, a slave process calls this function to
  send its exit status to the parent process and to notify
  the local <code>pvmd</code> of its exit.

 EXAMPLE

    pvm_ms_slave_exit (exit_status);


 SEE ALSO
  pvm_ms_run_slave

--------------------------------------------------------------

pvm_ms_run_slave

 SYNOPSIS
  Execute the slave's assigned task in a subshell, then exit the PVM

 USAGE
  pvm_ms_run_slave (String_Type argv[])

 DESCRIPTION
   A slave process calls this function to run a command in a
   subshell and then exit the PVM.  The command line is
   constructed by concatenting the elements of an array of
   strings, `argv', delimited by spaces. The integer return
   value from the `system' call provides the exit status
   for the slave process.  After sending this value to its
   parent process, the slave notifies the PVM and exits.

 EXAMPLE

   pvm_ms_run_slave (argv);


 SEE ALSO
  pvm_ms_slave_exit

--------------------------------------------------------------

pvm_ms_run_master

 SYNOPSIS
  Submit a list of tasks to the PVM

 USAGE
  Struct_Type exit_status[] = pvm_ms_run_master (String_Type pgms[])

 DESCRIPTION
  This function is used to submit a managed list of tasks to
  the PVM.  The task list manager will try to ensure that all
  tasks are completed and, upon completion of the task list,
  will return an array of structures containing information
  about the results of each task.

 EXAMPLE
  To run the Unix command <it>ps xu</it> on a number of different
  hosts:

    variable slave_argv = Array_Type[n];
    slave_argv[*] = ["ps", "axu"];
    exit_status = pvm_ms_run_master (slave_argv);


 SEE ALSO
  pvm_ms_add_new_slave

--------------------------------------------------------------

pvm_ms_add_new_slave

 SYNOPSIS
  Add a new slave to the managed list

 USAGE
  pvm_ms_add_new_slave (String_Type argv[])

 DESCRIPTION
 This function may be used to add a new slave process
 while pvm_ms_run_master() is running, usually as a result
 of handling a message.

 EXAMPLE

    pvm_ms_add_new_slave ("vex");


 SEE ALSO
  pvm_ms_run_master

--------------------------------------------------------------

pvm_ms_set_message_callback

 SYNOPSIS
  Set a callback for handling user-defined messages

 USAGE
  pvm_ms_set_message_callback (Ref_Type func)

 DESCRIPTION
 This function may be used to handle user-defined messages
 be sent from slave processes back to the master process.

 EXAMPLE


 static define handle_user_message (msgid, tid)
 {
    switch (msgid)
      {
       case USER_SLAVE_RESULT:
           recv_results (tid);
           start_task (tid);
      }
      {
       case USER_SLAVE_READY:
           start_task (tid);
      }
      {
         % default:
           return 0;
      }
    return 1;
 }

 pvm_ms_set_message_callback (&handle_user_message);



 SEE ALSO
  pvm_ms_set_idle_host_callback, pvm_ms_set_slave_exit_failed_callback

--------------------------------------------------------------

pvm_ms_set_slave_exit_failed_callback

 SYNOPSIS
  Set a hook to be called when a slave exits on failure

 USAGE
  pvm_ms_set_slave_exit_failed_callback (Ref_Type func)

 DESCRIPTION

 This function may be used to have the master process perform a
 specified action whenever a slave process exits without having
 completed its assigned task.

 This is primarily useful in the context where each command-line
 submitted to `pvm_ms_run_master' represents a task which
 itself communicates with the PVM, performing potentially many
 additional tasks which are independently managed by the
 process that called `pvm_ms_run_master'.

 For example, consider a case in which initialization of slave
 processes is very expensive but, once initialized, a single
 slave process may perform many tasks.  In this case, the
 master process may spawn a small number of slaves and then
 repeatedly send each slave a task to perform.  Each slave
 performs its task, sends the result to the master, and then
 waits for another task. The managing process must keep track
 of which tasks have been completed and which remain. If a
 slave exits while working on a task, it is important that the
 manager process be notified that that task in progress was not
 completed and that it should be reassigned to another slave.

 EXAMPLE


   static define slave_exit_failed_callback (msgid, tid)
   {
      variable t = find_task_tid (tid);

      if (orelse {t == NULL} {t.status == FINISHED})
        return;

      % mark the unfinished task "READY" so that it will
      % be assigned to another slave

      t.tid = -1;
      t.status = READY;
   }

   pvm_ms_set_slave_exit_failed_callback (&slave_exit_failed_callback);


 SEE ALSO
  pvm_ms_set_message_callback

--------------------------------------------------------------

pvm_ms_set_slave_spawned_callback

 SYNOPSIS
  Set the slave spawned callback hook

 USAGE
  pvm_ms_set_slave_spawned_callback (Ref_Type func)

 DESCRIPTION

 This function may be used to specify a callback function to be
 called whenever a slave process has been spawned.  The callback
 function will be called with three arguments: the slave task
 id, the name of the host running the slave process, and an
 array of strings representing the argument list passed to the
 slave.

 EXAMPLE


   static define slave_spawned_callback (tid, host, argv)
   {
      vmessage ("Slave running %s spawned on %s with task-id %d",
                argv[0], host, tid);
   }
   pvm_ms_set_slave_spawned_callback (&slave_spawned_callback);


 SEE ALSO
  pvm_ms_set_message_callback

--------------------------------------------------------------

pvm_ms_set_idle_host_callback

 SYNOPSIS
  Set the idle host hook

 USAGE
  pvm_ms_set_idle_host_callback (Ref_Type func)

 DESCRIPTION
 This function may be used to specify a callback function to be
 called whenever a new host is added to the virtual machine.

 EXAMPLE


 static define idle_host_callback ()
 {
    loop (Max_Num_Processes_Per_Host)
      {
         variable slave_argv = build_slave_argv (0);
         pvm_ms_add_new_slave (slave_argv);
      }
 }
 pvm_ms_set_idle_host_callback (&idle_host_callback);


 SEE ALSO
  pvm_ms_set_message_callback

--------------------------------------------------------------

pvm_ms_set_hosts

 SYNOPSIS
  Set list of hosts to use

 USAGE
  pvm_ms_set_hosts (String_Type hosts[])

 DESCRIPTION
  This function may be used to specify which hosts will be used
  to perform distributed calculations.  The default is to use
  all hosts in the current PVM.

 EXAMPLE

      pvm_ms_set_hosts (["vex", "pirx", "aluche"]);


 SEE ALSO
  pvm_addhosts

--------------------------------------------------------------