1PSEND(2) LAM NETWORK LIBRARY PSEND(2)
2
6 psend, precv, psendopen, precvopen, psendclose, precvclose - LAM
7 physical layer message passing (virtual circuits)
8
10 #include <net.h>
11 int psend (struct nmsg *header);
13 int precv (struct nmsg *header);
14 int psendopen (struct nmsg *header);
15 int precvopen (struct nmsg *header);
16 int psendclose (struct nmsg *header);
17 int precvclose (struct nmsg *header);
18
20 subroutine PSND (pnode, pevent, ptype, plength, pflags, pdata, pdsize,
21 pmsg, ierror)
22subroutine PSNDO (pnode, pevent, ptype, ierror)
23subroutine PSNDC (pnode, pevent, ptype, ierror)
24subroutine PRCV (pevent, ptype, plength, pflags, pdata, pdsize, pmsg, ierror)
26subroutine PRCVO (pevent, ptype, ierror)
27subroutine PRCVC (pevent, ptype, ierror)
28integer pnode, pevent, ptype, plength, pflags, pdata(*), pdsize, ierror
30<type> pmsg(*)
31
33 These functions use physical connections to establish LAM virtual cir‐
34 cuits. A user can establish a virtual circuit, pass messages on it,
35 and dismantle it when no longer needed. Virtual circuits provide the
36 fastest LAM point-to-point communication speeds, bypassing the LAM dae‐
37 mon, transferring the messages using the underlying physical connec‐
38 tions. All of these functions accept a pointer to a network message
39 descriptor (see nsend(2)).
40 The psendopen() and the precvopen() functions are used, by the sender
42 and receiver respectively, to establish a point-to-point virtual cir‐
43 cuit between them. To establish a virtual circuit, the sender sets the
44 nh_node field of the message descriptor to the receiver's nodeid, and
45 the nh_event and nh_type fields to specify the synchronization just as
46 in regular message passing (see nsend(2)). These fields are not
47 changed after a call to psendopen(). On the receiver side, the
48 nh_event and nh_type fields have to be set in order for synchronization
49 to take place. After a call to precvopen(), the nh_event field is un‐
50 changed but the nh_type field is set to the sender's nh_type field in
51 order to fully specify the correct virtual circuit created. Calling
52 psendopen() and precvopen() causes the sender and the receiver to block
53 until synchronization takes place and a virtual circuit is created.
54 After successful calls to psendopen() and precvopen() a virtual circuit
56 is established and will be used to quickly transfer messages whenever
57 the sender calls psend() and the receiver calls precv() on the nodeid,
58 event, and type specified during its creation. psend() and precv() are
59 otherwise used to transfer messages just as nsend() and nrecv() would
60 be, and any mismatch in the message length is handled in a similar man‐
61 ner (see nsend(2)). Likewise, the data conversion flags can be set by
62 the sender in order for LAM to change the contents of nh_data and
63 nh_msg to the proper local byte order at the receiver. Calling psend()
64 and precv() causes the sender and receiver to block until the message
65 exchange is completed.
66 Since virtual circuits use resources, it is preferable to close them
68 when they are no longer needed. The sender closes a virtual circuit by
69 calling the psendclose() function, specifying the node, event, and type
70 of that virtual circuit. The receiver closes a virtual circuit by
71 calling the precvclose() functions, specifying the event and the type
72 as returned by the precvopen() function. The psendclose() and precv‐
73 close() functions cause no synchronization to take place and are non-
74 blocking. They simply free the resources used to create the virtual
75 circuit.
76
78 This is an example code showing how a virtual circuit is used to send
79 an array of 4-byte floating point numbers from node n1 to node n0, us‐
80 ing event 6 and type 0. Error codes are not checked in order to keep
81 the code simple.
82 The sender on node n1 executes the following code:
84 float4 data[5];
86 struct nmsg header;
87 header.nh_node = 0;
89 header.nh_event = 6;
90 header.nh_type = 0;
91 psendopen(&header);
93 header.nh_msg = (char *) data;
95 header.nh_length = 5 * sizeof(float4);
96 header.nh_flags = DFLT4MSG;
97 psend(&header);
99 psendclose(&header);
101 The receiving process on node n0, not knowing how many floating point
103 numbers are going to be sent, sets a maximum limit of 20. precv() mod‐
104 ifies the value of nh_length in the header to indicate the length of
105 the received message, i.e. four times the number of numbers sent. The
106 receiver executes the following code:
107 float4 indata[20];
109 int4 num;
110 struct nmsg header;
111 header.nh_event = 6;
113 header.nh_type = 0;
114 precvopen(&header);
116 header.nh_msg = (char *) indata;
118 header.nh_length = 20 * sizeof(float4);
119 header.nh_flags = DFLT4MSG;
120 precv(&header);
122 num = header.nh_length / 4;
124 precvclose(&header);
126
128 EFULL The virtual circuit table is full.
129 EINVAL The virtual circuit is invalid. If returned by
131 psendopen() or precvopen() this means the virtual cir‐
132 cuit is already open. Otherwise it means the virtual
133 circuit does not exist.
134
136 In the current implementation, the sender and receiver have to be on
137 different nodes. The factory default size of the virtual circuit table
138 is 67.
139
141 nsend(2)
142LAM 7.1.2 March, 2006 PSEND(2)