S-Lang PVM Module Reference: Master-Slave Function Reference

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