1KSEND(2)                       LAM LOCAL LIBRARY                      KSEND(2)
2
3
4

NAME

6       ksend, krecv, ksr - Send and receive local node LAM messages.
7

SYNOPSIS

9       #include <kreq.h>
10
11       int ksend (struct kmsg *desc);
12       int krecv (struct kmsg *desc);
13       int ksr (struct kmsg *sdesc, struct kmsg *rdesc);
14

DESCRIPTION

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
22   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
28              struct kmsg {
29                   int  k_event;
30                   int  k_type;
31                   int  k_length;
32                   int  k_flags;
33                   char *k_msg;
34              };
35
36       The usage of each field in the local message structure is  defined  be‐
37       low.
38
39       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
44       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
52              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
56              After  calling  krecv(), the receiver's k_type field is replaced
57              with the sender's k_type field.
58
59       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
66       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
74       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
78       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

RETURN VALUE

90       Upon successful completion, 0 is returned.  Otherwise, -1  is  returned
91       and the global variable errno is set to indicate the error.
92

ERRORS

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

BUGS

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

SEE ALSO

106       kinit(2), nsend(2), nrecv(2)
107
108
109
110LAM 7.1.2                         March, 2006                         KSEND(2)
Impressum