Chapter 3. Functions and Subroutines

Chapter 3. Functions and Subroutines
Prev		Next

This chapter provides general information about PVM error messages and include files, and briefly describes tasks and associated functions.

You can use the C and Fortran interfaces to the PVM library functions to perform the following kinds of tasks:

Basic operations (see “Basic Operations”)
Task control (see “Task Control”)
Option management (see “Option Management”)
Dynamic system configuration (see “Dynamic System Configuration”)
Dynamic task group management (see “Dynamic Task Group Management”)
Data transmittal (see “Data Transmittal”)
Data receipt (see “Data Receipt”)
Barrier synchronization (see “Barrier Synchronization”)
Global operations (see “Global Operations”)
Signaling (see “Signaling”)
Error handling (see “Error Handling”)

This chapter briefly describes these tasks. The functions associated with each task are listed in a table. In each table, the functions are grouped as they are described on the man pages, and the groups are listed in the order you usually use them to perform the tasks.

In most cases, each logical PVM function is represented by a C function and a Fortran subroutine. For more information about a specific function or subroutine, use the man(1) command to view the associated man page online. To simplify references, this discussion refers to C functions, C++ functions, and Fortran subroutines as functions unless individual differences require documentation.

When the C interfaces specify char * as a data type, the Fortran interfaces generally permit specification of Fortran character variables or constants. However, these Fortran values are processed as C strings; therefore, a null character in the middle of the character sequence, which is valid in Fortran, terminates the string.

Error Messages

For a complete list of the PVM error messages and the value associated with each, see Appendix A, “PVM Error Messages”. In general, PVM functions return PvmOk (0) or a negative number for errors. Some functions return positive values with other meanings or have special return codes. Error checks should be coded as less than 0, rather than not equal to 0.

You can control the actions that PVM takes when it detects an error. The default is to print an ASCII message and return an error code to the caller. For more information, see the pvm_setopt(3) man page for a description of the PvmAutoErr option.

Process Identifiers

All processes that enroll in PVM are represented by an integer task identifier, a pvm_tid. Because pvm_tid values must be unique across the entire virtual machine, they are supplied by PVM and are not chosen by the user. The following routines return pvm_tid values:

pvm_bufinfo(3)

pvm_gettid(3)

pvm_mytid(3)

pvm_parent(3)

pvm_spawn(3)

PVM Include Files

PVM include files for the MPT release are installed in the $PVM_ROOT/include directory. If the mpt module has been loaded, this include file directory will be searched before any standard include directories.

For better portability, you can refer to PVM include files in your source and specify the include file directory on the compiler command line, as follows:

From C:

#include <pvm3.h>
cc -I $PVM_ROOT/include

From Fortran:

include "fpvm3.h"
f90 -I $PVM_ROOT/include

Basic Operations

You can perform basic PVM operations by using the functions in Table 3-1.

Table 3-1. Basic Operations Functions

C and C++ function	Fortran subroutine	Description
`_my_pe`	`MY_PE`	Returns the PE number of the PVM task that calls it
`_num_pes`	`NUM_PES`	Returns the total number of PEs (or PVM tasks) in the program
`pvm_freezegroup`	`PVMFFREEZEGROUP`	Freezes dynamic group membership and caches information locally
`pvm_get_PE`	`PVMFGETPE`	Converts a task ID into a PE number
`pvm_hostsync`	`PVMFHOSTSYNC`	Gets the time-of-day clock from the PVM host
`pvm_mytid`	`PVMFMYTID`	Returns the `pvm_tid` of the calling task
`pvm_parent`	`PVMFPARENT`	Returns the `pvm_tid` for the task that spawned the calling task
`pvm_tidtohost`	`PVMFTIDTOHOST`	Returns the `pvm_tid` for the PVM daemon task

Task Control

You can control PVM process creation and termination by using the task control functions in Table 3-2.

Table 3-2. Task Control Functions

C and C++ function	Fortran subroutine	Description
`pvm_catchout`	`PVMFCATCHOUT`	Catches output from child tasks
`pvm_exit`	`PVMFEXIT`	Exits PVM
`pvm_halt`	`PVMFHALT`	Shuts down the entire PVM system
`pvm_kill`	`PVMFKILL`	Terminates a PVM task
`pvm_pstat`	`PVMFPSTAT`	Determines if a PVM task is executing
`pvm_reg_hoster`	(Not applicable)	Registers a task as the PVM host starter
`pvm_reg_tasker`	(Not applicable)	Registers a task as the PVM task starter
`pvm_spawn`	`PVMFSPAWN`	Starts a new PVM task

Option Management

You can control PVM options by using the functions in Table 3-3.

Table 3-3. Option Management Functions

C and C++ function	Fortran subroutine	Description
`pvm_setopt`	`PVMFSETOPT`	Sets a PVM option
`pvm_getopt`	`PVMFGETOPT`	Returns the current value of a PVM option

Dynamic System Configuration

The dynamic system configuration functions, described in Table 3-4, allow PVM to be dynamically configured by the application. Systems may be added or removed from the virtual machine, and information can be obtained about a particular system or about the virtual machine as a whole.

Table 3-4. Dynamic System Configuration Functions

C and C++ function	Fortran subroutine	Description
`pvm_addhosts` `pvm_delhosts`	`PVMFADDHOST` `PVMFDELHOST`	Adds or deletes one or more systems
`pvm_config`	`PVMFCONFIG`	Returns the configuration of the virtual machine
`pvm_mstat`	`PVMFMSTAT`	Returns the status of the specified system
`pvm_tasks`	`PVMFTASKS`	Returns information about tasks

Dynamic Task Group Management

A PVM application can form dynamic groups of tasks during its execution. Usually, these groups are established to simplify multicasting (the broadcast of data to a number of tasks) and barrier synchronization. Tasks can join and leave groups as desired.

A group is identified by a character string that is assigned by the user. All tasks that want to join a group must specify the same character string.

Dynamically joining and leaving a group must be done with care. Synchronization problems can arise if, for example, one task is joining a group at the same time another task is broadcasting a message to the group. Participating tasks should synchronize at a barrier before trying to use a group.

Dynamic task group management functions are described in Table 3-5.

Table 3-5. Dynamic Task Group Management Functions

C and C++ function	Fortran subroutine	Description
`pvm_getinst`	`PVMFGETINST`	Returns the instance number of a task
`pvm_gettid`	`PVMFGETTID`	Returns the `pvm_tid` for a task
`pvm_gsize`	`PVMFGSIZE`	Returns the number of tasks in a group
`pvm_joingroup` `pvm_lvgroup`	`PVMFJOINGROUP` `PVMFLVGROUP`	Joins or leaves a dynamic group

Data Transmittal

There are two methods in PVM for sending messages. The simpler method, which involves the use of the pvm_psend(3) function, lets you make a single call to transmit a contiguous block of data to another PVM task.

The more complex method involves three steps:

Initializing a send buffer
Packing one or more blocks of data into the buffer
Transmitting the buffer to one or more tasks

The second method is more powerful and flexible than the first, but runs more slowly. Messages can be sent to a particular task, can be broadcast to all members of a group, can be broadcast to all tasks, or can be multicast to a list of tasks.

You can use the data transmittal functions in Table 3-6, to transmit data.

Table 3-6. Data Transmittal Functions

C and C++ function	Fortran subroutine	Description
`pvm_bcast`	`PVMFBCAST`	Broadcasts a message to all tasks in a group.
`pvm_getsbuf`	`PVMFGETSBUF`	Returns the buffer identifier of the current send buffer.
`pvm_initsend`	`PVMFINITSEND`	Initializes a send buffer.
`pvm_mcast`	`PVMFMCAST`	Broadcasts a message to all tasks in an array.
`pvm_mkbuf` `pvm_freebuf`	`PVMFMKBUF` `PVMFFREEBUF`	Creates send buffers or releases buffers.
`pvm_psend`	`PVMFPSEND`	Packs and sends data in one call.
`pvm_pkint` `pvm_pkshort` `pvm_pklong` `pvm_pkuint` `pvm_pkushort` `pvm_pkulong` `pvm_pkfloat` `pvm_pkdouble` `pvm_pkcplx` `pvm_pkdcplx` `pvm_pkbyte` `pvm_pkstr` `pvm_packf`	`PVMFPACK`	Inserts data values into the send buffer. See `pvm_pk`(3).
`pvm_send`	`PVMFSEND`	Sends a message to a single task.
`pvm_setsbuf`	`PVMFSETSBUF`	Specifies a new buffer as the current send buffer.

Data Receipt

There are two methods in PVM for receiving messages. The simpler method, which involves the use of the pvm_precv(3) function, lets you make a single call to receive a message and store its data into a contiguous block of data. This is a blocking receive; the calling task does not return until an appropriate message arrives.

The more complex method involves two steps:

Receiving a message. (You can choose either a blocking or a nonblocking form of receive.)
Unpacking one or more blocks of data from the message.

Both methods allow you to choose the message to receive. You can choose to receive a message of any of the following types:

A message with a specific message tag sent by a specific PVM task
Any message sent by a specific PVM task
A message with a specific message tag sent by any PVM task
Any message at all

In addition, PVM provides an optional capability that lets you select a message based on any criteria (including the contents of the message itself). To use this feature, you must write a comparison function (in C) and call pvm_recvf(3) or pvm_trecv(3). PVM then calls this comparison function on each subsequent pvm_recv(3) or pvm_nrecv(3) call to identify the message that should be selected.

After a message has been received, the data is available in an internal receive buffer, and additional functions must be called to transfer (and convert) this data into user buffers. Any combination and number of calls to the unpacking functions may be made to move this data into user memory, but it is recommended that the sequence of unpacking calls match the sequence of packing calls that built up the data for the message. It may be possible to use a different sequence, but you should be aware that this depends on undocumented, underlying data packing and transfer mechanisms. (This is particularly dangerous if you use pvm_pkstr(3) or if you use pvm_pkbyte(3) with a byte count that is not a multiple of 8. Also, if you ever anticipate using this code on another system or across heterogeneous systems, you should avoid using a different sequence.)

The data receipt functions are described in Table 3-7.

Table 3-7. Data Receipt Functions

C and C++ function	Fortran subroutine	Description
`pvm_bufinfo`	`PVMFBUFINFO`	Returns information about a message.
`pvm_freebuf`	`PVMFFREEBUF`	Releases receive buffers. See `pvm_mkbuf`(3).
`pvm_getrbuf`	`PVMFGETRBUF`	Returns the buffer identifier of the current receive buffer.
`pvm_precv`	`PVMFPRECV`	Receives a message directly into a buffer.
`pvm_recv` `pvm_nrecv` `pvm_probe`	`PVMFRECV` `PVMFNRECV` `PVMFPROBE`	Receives a message or probes for a message.
`pvm_recvf`	(Not applicable)	Supplies a user-written comparison function.
`pvm_setrbuf`	`PVMFSETRBUF`	Specifies a new buffer as the current receive buffer.
`pvm_trecv`	`PVMFTRECV`	Receives a message with a time-out.
`pvm_upkint` `pvm_upkshort` `pvm_upklong` `pvm_upkuint` `pvm_upkushort` `pvm_upkulong` `pvm_upkfloat` `pvm_upkdouble` `pvm_upkcplx` `pvm_upkdcplx` `pvm_upkbyte` `pvm_upkstr` `pvm_unpackf`	`PVMFUNPACK`	Extracts values from received messages. See `pvm_upk`(3).

Barrier Synchronization

The pvm_barrier(3) function described in Table 3-8 lets PVM tasks explicitly synchronize with one another. Calling this function causes the task to block (wait) until a specified number of tasks in a group have called the function. When this occurs, all waiting tasks are unblocked. The calling task must be a member of the group, and the count argument must be the same for all tasks that use the same barrier.

The barrier(3) function described in Table 3-8 lets multitasked PVM tasks explicitly synchronize with one another. This function is useful when PVM is being used in stand-alone mode for global synchronization between all multitasked PVM tasks.

Table 3-8. Barrier Synchronization Function

C and C++ function	Fortran subroutine	Description
`barrier`	`BARRIER`	Creates a barrier to synchronize multitasked PVM tasks
`pvm_barrier`	`PVMFBARRIER`	Creates a barrier to synchronize tasks

Global Operations

The functions in Table 3-9 allow the tasks in a group to participate in a global operation. All tasks in the group must call the same function at the same time.

The pvm_reduce(3) function supports sum, product, max, and min operations, as well as user-defined operations.

Table 3-9. Global Operations Functions

C and C++ function	Fortran subroutine	Description
`pvm_gather`	`PVMFGATHER`	Gathers data from group members into an array
`pvm_reduce`	`PVMFREDUCE`	Performs a reduction operation across a group
`pvm_scatter`	`PVMFSCATTER`	Sends a section of an array to each member of the group

Signaling

The functions in Table 3-10 support sending signals of different kinds to PVM tasks.

Table 3-10. Signaling Functions

C and C++ function	Fortran subroutine	Description
`pvm_notify`	`PVMFNOTIFY`	Notifies tasks of specific events
`pvm_sendsig`	`PVMFSENDSIG`	Sends a signal to a task

Error Handling

The function in Table 3-11 provides simple help for handling PVM-generated errors.

Table 3-11. Error Handling Function

C and C++ function	Fortran subroutine	Description
`pvm_perror`	`PVMFPERROR`	Outputs a PVM error message

For more information on controlling PVM behavior, see the pvm_setopt(3) man page.

Prev	Table of Contents	Next
Chapter 2. PVM Functionality		Appendix A. PVM Error Messages