Linux Certif

Toute la documentation sur la certification Linux LPI

precv

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 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

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, using 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() 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:

 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)