1KSEND(2) LAM LOCAL LIBRARY KSEND(2)
2
6 ksend, krecv, ksr - Send and receive local node LAM messages.
7
9 #include <kreq.h>
10 int ksend (struct kmsg *desc);
12 int krecv (struct kmsg *desc);
13 int ksr (struct kmsg *sdesc, struct kmsg *rdesc);
14
16 These communication routines send and receive messages among processes
17 on the local node. The LAM daemon arranges for the two processes to
18 synchronize. The process calling ksend() always blocks unless a re‐
19 ceiver is already waiting, blocked on krecv(). The reverse is also
20 true.
21 Local Message Structure
23 The argument passed to these routines is a pointer to a local message
24 description, the fields of which must be filled before the message is
25 sent or received. The kmsg structure is defined in <kreq.h> as shown
26 below.
27 struct kmsg {
29 int k_event;
30 int k_type;
31 int k_length;
32 int k_flags;
33 char *k_msg;
34 };
35 The usage of each field in the local message structure is defined be‐
37 low.
38 k_event
40 An event is an arbitrary integer used to synchronize processes
41 on the same node. The sender and the receiver must specify the
42 same positive integer.
43 k_type A type is an arbitrary bit field used in conjunction with an
45 event to synchronize processes on the same node. A message will
46 be passed only if the k_type fields of the sender and receiver
47 have at least one bit set in an identical position. In other
48 words, the bitwise logical AND of the type fields specified by
49 the two parties must not equal zero. A zero value in the k_type
50 field is a special case - it will match any other type.
51 Two LAM processes on the same node synchronize and pass a mes‐
53 sage when one calls ksend() and the other calls krecv() with
54 identical events and matching types.
55 After calling krecv(), the receiver's k_type field is replaced
57 with the sender's k_type field.
58 k_length
60 This field holds the length (in bytes) of the sender's message
61 or the receiver's buffer. If the sender and the receiver speci‐
62 fy different lengths, the lesser amount will be transferred.
63 This field is set to the minimum of the sender's and receiver's
64 message length after calling ksend() or krecv().
65 k_flags
67 The k_flags field is normally set to 0. The KTRY flag, defined
68 in <kreq.h>, prevents ksend() or krecv() from blocking. The
69 message is transferred if a synchronizing process is blocked.
70 If not, an error condition is returned. Never use the non-
71 blocking feature for both sender and receiver processes or syn‐
72 chronization will never occur.
73 k_msg This field holds the address of the first byte of the sender's
75 message or the first byte of the receiver's buffer. The data
76 must be stored contiguously in memory.
77 The ksr() routine is an atomic send/receive operation. The first mes‐
79 sage description argument is used in the equivalent of ksend(). Then
80 the second message description argument is used in the equivalent of
81 krecv(). After the send half synchronizes and transfers the message,
82 the process immediately becomes receive blocked. There is no interven‐
83 ing period in the ready state. This atomic transition from send to re‐
84 ceive is used in local client processes to make the corresponding
85 servers more robust. If the client uses ksr(), the server can respond
86 with the KTRY feature, and guarantee non-blocking behaviour, even if
87 the client process should die while the server request is processed.
88
90 Upon successful completion, 0 is returned. Otherwise, -1 is returned
91 and the global variable errno is set to indicate the error.
92
94 EWOULDBLOCK Non-blocking behaviour was selected and the operation
95 would have caused the calling process to block. No oth‐
96 er process is blocked on an identical type and matching
97 event.
98
100 Both sides of ksr() must synchronize with the same process. Whoever
101 receives the first message (and no other process) must send a message
102 back to satisfy the receive. This reduces overhead in the daemon and
103 is within the constraints of client/server usage.
104
106 kinit(2), nsend(2), nrecv(2)
107LAM 7.1.2 March, 2006 KSEND(2)