1DSEND(2) LAM NETWORK LIBRARY DSEND(2)
2
6 dsend, dtry_send, drecv, dtry_recv - Send and receive LAM datalink mes‐
7 sages.
8
10 #include <net.h>
11 #include <events.h>
12 int dsend (struct nmsg *header);
14 int dtry_send (struct nmsg *header);
15 int drecv (struct nmsg *header);
16 int dtry_recv (struct nmsg *header);
17
19 These datalink functions pass a network message from one process to
20 another and are the basis for all forms of LAM network communication.
21 Although they can be invoked directly, they are most often called by
22 the network and transport functions. The datalink functions do not
23 supply message routing, buffering or packetization. The user supplies
24 the event of the forwarding process and the message length is
25 restricted to MAXNMSGLEN, defined in <net.h>.
26 dsend() and drecv() are typically used to send messages to, or receive
28 messages from, nearest neighbour nodes (see "Typical Usage").
29 dtry_send() and dtry_recv() never cause the calling process to block.
30 The message is either immediately transferred, or an error is immedi‐
31 ately returned, indicating that the process would have blocked.
32 Network Message Structure
34 All of the functions accept a pointer to a message structure which is
35 an extension of the local level message structure used by ksend(2) and
36 krecv(2). The network message structure is defined in <net.h> as:
37 struct nmsg {
39 int nh_dl_event;
40 int nh_dl_link;
41 int nh_node;
42 int nh_event;
43 int nh_type;
44 int nh_length;
45 int nh_flags;
46 int nh_data[NHDSIZE];
47 char *nh_msg;
48 };
49 The usage of each field in the network message structure is described
51 below.
52 nh_dl_event
54 This field is used by dsend() to synchronize the sending process
55 and a) a forwarding process such as a link output process, or b)
56 a local receiving process. In the first case, the synchroniza‐
57 tion is between nh_dl_event and the published event of the for‐
58 warding process. The forwarding event is returned by
59 getroute(2). In the second case, the synchronization is between
60 nh_dl_event and the local receiver's nh_event field. The
61 nh_dl_event field is not used by drecv().
62 The nh_dl_event field remains unchanged after calling dsend() or
64 drecv().
65 nh_dl_link
67 If nh_dl_event refers to a link output process, a specific link
68 number must be given in the nh_dl_link field. Link output pro‐
69 cesses may handle multiple links. This field is not used by
70 drecv().
71 The nh_dl_link field remains unchanged after calling dsend() or
73 drecv().
74 nh_node
76 This field is used by dsend() to identify the remote node run‐
77 ning the intended receiver. Typically, the destination node is
78 an immediate neighbour of the local node. The nh_node field is
79 not used by drecv(). A receiving process thus cannot directly
80 specify the source node of a message. Instead, receiving pro‐
81 cesses are "matched" to messages by one or both of nh_event and
82 nh_type.
83 The nh_node field is never altered.
85 nh_event
87 An event is an arbitrary positive integer used by the LAM daemon
88 to synchronize processes within a node. Synchronization occurs
89 when two events are equal. In a datalink transfer, nh_dl_event
90 in the sender equals nh_event in the local receiver. When the
91 local receiver is a forwarding process, the message begins a
92 journey through the network system. Much more than one simple
93 datalink transfer is taking place and the sender must give more
94 information beyond nh_dl_event in the nh_node and nh_event
95 fields. The message may be transmitted through a physical com‐
96 munication link to a neighbour node. On the destination remote
97 node, the nh_event given by the original sender is copied to
98 nh_dl_event and another typical datalink transfer occurs between
99 a system process and the ultimate intended receiver calling
100 drecv(). Thus, the sender calling dsend() must set nh_event to
101 the same value as the intended receiver calling drecv(). If the
102 datalink functions present too much complexity, try nsend(2) and
103 nrecv(2).
104 The nh_event field is never altered.
106 nh_type
108 This field further filters messages that match on event. A mes‐
109 sage will be passed only if the nh_type fields of the sender and
110 receiver processes have at least one bit set in an identical
111 position. In other words, the bitwise logical AND of the type
112 fields specified by the two parties must not equal zero. A zero
113 value matches any other value of nh_type. The dsend() function
114 compares nh_dl_event and nh_event to decided if the receiver is
115 a forwarding process. If they are equal, nh_type is used as
116 described above. Otherwise, usage of nh_type is deferred until
117 the message arrives at the destination node for synchronization
118 with the ultimate intended receiver and special type values are
119 immediately used to codify the message and control synchroniza‐
120 tion with the forwarding process. If nh_event is negative, a
121 type signifying a system message is used, otherwise the type
122 identifies a user message. Application programs should not
123 directly specify negative values for nh_event. If the datalink
124 functions present too much complexity, try nsend(2) and
125 nrecv(2).
126 The nh_type field remains unchanged after calling dsend(), but
128 is set to the sender's nh_type after calling drecv().
129 nh_length
131 This field holds the length (in bytes) of the message to be
132 sent. If the sender and the receiver specify different lengths,
133 the lesser amount will be transferred. The maximum length of
134 messages transferred with dsend() and drecv() is MAXNMSGLEN,
135 defined in <net.h> and usually set to 8192 bytes. Forwarding
136 processes in the LAM network subsystem always use MAXNMSGLEN.
137 The nh_length field remains unchanged after calling dsend(), but
139 is set to the minimum of the sender's and receiver's lengths
140 after calling drecv().
141 nh_flags
143 This field is normally set to 0. Flags used to ensure that the
144 data representation is correct for the receiving node are dis‐
145 cussed under "Data Representation".
146 The nh_flags field is never altered.
148 nh_data
150 This field is a convenient data pouch within the network message
151 descriptor. Its array size is NHDSIZE words, which is defined
152 in <net.h> and is currently set to 8. It can be used for send‐
153 ing short messages (in which case nh_length is set to 0) or for
154 appending control information to the message body.
155 After calling drecv() the nh_data field is overwritten with the
157 sender's values of the same field. The sender's nh_data will
158 not change.
159 nh_msg This field holds the address of the first byte of data to be
161 sent or received. The data must be stored contiguously in mem‐
162 ory.
163 The nh_msg field is never altered.
165 Data Representation
167 On nodes of different architectures, data may have different represen‐
168 tations. For example, integers may be stored with the most significant
169 byte first in memory (big-endian) or with the most significant byte
170 last in memory (little-endian). Also, the representation of floating
171 point numbers may conform to the IEEE standard or may follow a vendor
172 specific format. All fields in the network message structure, except
173 the data referenced by nh_msg, are automatically converted if passed to
174 a node with different data representation. The nh_data field is
175 assumed to hold all integers.
176 The nh_flags field of the message structure can be set to the following
178 data representation flags. Each flag assumes a data type, and will
179 make the appropriate change in the data representation of the given
180 field. They will have no effect if data conversion is not needed.
181 DINT4DATA nh_data holds 8 32-bit integers (default).
183 DFLT4DATA nh_data holds 8 single 32-bit real numbers.
185 DFLT8DATA nh_data holds 4 64-bit real numbers.
187 DRAWDATA nh_data representation will not be changed.
189 DINT4MSG nh_msg points to 32-bit integers.
191 DFLT4MSG nh_msg points to 32-bit real numbers.
193 DFLT8MSG nh_msg points to 64-bit real numbers.
195 DRAWMSG nh_msg representation will not be changed (default).
197 If nh_data or nh_msg contains a mixture of data types, the user will
199 have to change the representation using the functions ltoti4(3),
200 ttoli4(3), etc.
201 Typical Usage
203 The typical usage of the datalink functions is for nearest neighbour
204 message passing, when the user wishes to avoid the expense of automatic
205 message routing (as provided by nsend(2)) and other network level over‐
206 heads. To synchronize the sender and receiver, the sender must set
207 nh_node to the destination neighbour's node ID, nh_dl_event to the link
208 process event connecting the neighbour node, nh_dl_link to the specific
209 link number and nh_event to its counterpart in the receiver.
210 Blocking
212 A process calling drecv() blocks until the message sent by the process
213 calling dsend() entirely arrives. A process calling dsend() blocks
214 only until its message is picked up by a) a local receiver calling
215 drecv() or b) the local forwarding process identified by nh_dl_event.
216 The only thing that is guaranteed by a successful return from dsend()
217 is that the message has entirely left the calling process.
218 The loose blocking behaviour of dsend() introduces a fundamental danger
220 of LAM message passing: a sender can transmit a message that may never
221 be received due to programming error or deadlock. This message will
222 never be dropped or timed out. Some LAM process will always be stuck
223 with it, waiting for a synchronizing drecv() that may never happen. If
224 the process is a link proprietor, the link could become plugged and
225 useless. A link input process may hold one message. A link output
226 process may hold several messages, depending on its internal implemen‐
227 tation.
228
230 EWOULDBLOCK One of the non-blocking functions, dtry_send() or
231 dtry_recv(), failed because the message could not be
232 sent or received, respectively. A call to dsend() or
233 drecv() would have blocked.
234
236 nsend(2), tsend(2)
237LAM 7.1.2 March, 2006 DSEND(2)