PSEND (2)
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
0
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(*)
1
DESCRIPTION
These functions use physical connections to establish LAM virtual circuits.
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 daemon, transferring the
messages using the underlying physical connections.
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 circuit 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 unchanged 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 manner (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
precvclose()
functions cause no synchronization to take place and are non-blocking.
They simply free the resources used to create the virtual circuit.
EXAMPLE USAGE
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()
modifies 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:
1.5i
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 circuit 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 ALSO
- nsend (2) -
man2/psend 2 man2/PSND 2 man2/PSND 2
|