Next Previous Contents

4. Master-Slave Function Reference

4.1 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

4.2 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

4.3 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

4.4 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 pvmd of its exit.

Example

    pvm_ms_slave_exit (exit_status);

See Also

pvm_ms_run_slave

4.5 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

4.6 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 ps xu 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

4.7 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

4.8 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

4.9 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

4.10 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

4.11 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

4.12 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


Next Previous Contents