PSEND(2) LAM NETWORK LIBRARY PSEND(2)NAME
psend, precv, psendopen, precvopen, psendclose, precvclose - LAM
physical layer message passing (virtual circuits)
C SYNOPSIS
#include <net.h>
int psend (struct nmsg *header);
int precv (struct nmsg *header);
int psendopen (struct nmsg *header);
int precvopen (struct nmsg *header);
int psendclose (struct nmsg *header);
int precvclose (struct nmsg *header);
FORTRAN SYNOPSIS
subroutine PSND (pnode, pevent, ptype, plength, pflags, pdata, pdsize,
pmsg, ierror)
subroutine PSNDO (pnode, pevent, ptype, ierror)
subroutine PSNDC (pnode, pevent, ptype, ierror)
subroutine PRCV (pevent, ptype, plength, pflags, pdata, pdsize, pmsg, ierror)
subroutine PRCVO (pevent, ptype, ierror)
subroutine PRCVC (pevent, ptype, ierror)
integer pnode, pevent, ptype, plength, pflags, pdata(*), pdsize, ierror
<type> pmsg(*)
DESCRIPTION
These functions use physical connections to establish LAM virtual cir‐
cuits. A user can establish a virtual circuit, pass messages on it,
and dismantle it when no longer needed. Virtual circuits provide the
fastest LAM point-to-point communication speeds, bypassing the LAM dae‐
mon, transferring the messages using the underlying physical connec‐
tions. All of these functions accept a pointer to a network message
descriptor (see nsend(2)).
The psendopen() and the precvopen() functions are used, by the sender
and receiver respectively, to establish a point-to-point virtual cir‐
cuit between them. To establish a virtual circuit, the sender sets the
nh_node field of the message descriptor to the receiver's nodeid, and
the nh_event and nh_type fields to specify the synchronization just as
in regular message passing (see nsend(2)). These fields are not
changed after a call to psendopen(). On the receiver side, the
nh_event and nh_type fields have to be set in order for synchronization
to take place. After a call to precvopen(), the nh_event field is un‐
changed but the nh_type field is set to the sender's nh_type field in
order to fully specify the correct virtual circuit created. Calling
psendopen() and precvopen() causes the sender and the receiver to block
until synchronization takes place and a virtual circuit is created.
After successful calls to psendopen() and precvopen() a virtual circuit
is established and will be used to quickly transfer messages whenever
the sender calls psend() and the receiver calls precv() on the nodeid,
event, and type specified during its creation. psend() and precv() are
otherwise used to transfer messages just as nsend() and nrecv() would
be, and any mismatch in the message length is handled in a similar man‐
ner (see nsend(2)). Likewise, the data conversion flags can be set by
the sender in order for LAM to change the contents of nh_data and
nh_msg to the proper local byte order at the receiver. Calling psend()
and precv() causes the sender and receiver to block until the message
exchange is completed.
Since virtual circuits use resources, it is preferable to close them
when they are no longer needed. The sender closes a virtual circuit by
calling the psendclose() function, specifying the node, event, and type
of that virtual circuit. The receiver closes a virtual circuit by
calling the precvclose() functions, specifying the event and the type
as returned by the precvopen() function. The psendclose() and precv‐
close() functions cause no synchronization to take place and are non-
blocking. They simply free the resources used to create the virtual
circuit.
EXAMPLE USAGE
This is an example code showing how a virtual circuit is used to send
an array of 4-byte floating point numbers from node n1 to node n0, us‐
ing event 6 and type 0. Error codes are not checked in order to keep
the code simple.
The sender on node n1 executes the following code:
float4 data[5];
struct nmsg header;
header.nh_node = 0;
header.nh_event = 6;
header.nh_type = 0;
psendopen(&header);
header.nh_msg = (char *) data;
header.nh_length = 5 * sizeof(float4);
header.nh_flags = DFLT4MSG;
psend(&header);
psendclose(&header);
The receiving process on node n0, not knowing how many floating point
numbers are going to be sent, sets a maximum limit of 20. precv() mod‐
ifies the value of nh_length in the header to indicate the length of
the received message, i.e. four times the number of numbers sent. The
receiver executes the following code:
float4 indata[20];
int4 num;
struct nmsg header;
header.nh_event = 6;
header.nh_type = 0;
precvopen(&header);
header.nh_msg = (char *) indata;
header.nh_length = 20 * sizeof(float4);
header.nh_flags = DFLT4MSG;
precv(&header);
num = header.nh_length / 4;
precvclose(&header);
ERRORS
EFULL The virtual circuit table is full.
EINVAL The virtual circuit is invalid. If returned by
psendopen() or precvopen() this means the virtual cir‐
cuit is already open. Otherwise it means the virtual
circuit does not exist.
LIMITATIONS
In the current implementation, the sender and receiver have to be on
different nodes. The factory default size of the virtual circuit table
is 67.
SEE ALSOnsend(2)LAM 7.1.2 March, 2006 PSEND(2)
