KSEND(2) LAM LOCAL LIBRARY KSEND(2)NAME
ksend, krecv, ksr - Send and receive local node LAM messages.
SYNOPSIS
#include <kreq.h>
int ksend (struct kmsg *desc);
int krecv (struct kmsg *desc);
int ksr (struct kmsg *sdesc, struct kmsg *rdesc);
DESCRIPTION
These communication routines send and receive messages among processes
on the local node. The LAM daemon arranges for the two processes to
synchronize. The process calling ksend() always blocks unless a re‐
ceiver is already waiting, blocked on krecv(). The reverse is also
true.
Local Message Structure
The argument passed to these routines is a pointer to a local message
description, the fields of which must be filled before the message is
sent or received. The kmsg structure is defined in <kreq.h> as shown
below.
struct kmsg {
int k_event;
int k_type;
int k_length;
int k_flags;
char *k_msg;
};
The usage of each field in the local message structure is defined be‐
low.
k_event
An event is an arbitrary integer used to synchronize processes
on the same node. The sender and the receiver must specify the
same positive integer.
k_type A type is an arbitrary bit field used in conjunction with an
event to synchronize processes on the same node. A message will
be passed only if the k_type fields of the sender and receiver
have at least one bit set in an identical position. In other
words, the bitwise logical AND of the type fields specified by
the two parties must not equal zero. A zero value in the k_type
field is a special case - it will match any other type.
Two LAM processes on the same node synchronize and pass a mes‐
sage when one calls ksend() and the other calls krecv() with
identical events and matching types.
After calling krecv(), the receiver's k_type field is replaced
with the sender's k_type field.
k_length
This field holds the length (in bytes) of the sender's message
or the receiver's buffer. If the sender and the receiver speci‐
fy different lengths, the lesser amount will be transferred.
This field is set to the minimum of the sender's and receiver's
message length after calling ksend() or krecv().
k_flags
The k_flags field is normally set to 0. The KTRY flag, defined
in <kreq.h>, prevents ksend() or krecv() from blocking. The
message is transferred if a synchronizing process is blocked.
If not, an error condition is returned. Never use the non-
blocking feature for both sender and receiver processes or syn‐
chronization will never occur.
k_msg This field holds the address of the first byte of the sender's
message or the first byte of the receiver's buffer. The data
must be stored contiguously in memory.
The ksr() routine is an atomic send/receive operation. The first mes‐
sage description argument is used in the equivalent of ksend(). Then
the second message description argument is used in the equivalent of
krecv(). After the send half synchronizes and transfers the message,
the process immediately becomes receive blocked. There is no interven‐
ing period in the ready state. This atomic transition from send to re‐
ceive is used in local client processes to make the corresponding
servers more robust. If the client uses ksr(), the server can respond
with the KTRY feature, and guarantee non-blocking behaviour, even if
the client process should die while the server request is processed.
RETURN VALUE
Upon successful completion, 0 is returned. Otherwise, -1 is returned
and the global variable errno is set to indicate the error.
ERRORS
EWOULDBLOCK Non-blocking behaviour was selected and the operation
would have caused the calling process to block. No oth‐
er process is blocked on an identical type and matching
event.
BUGS
Both sides of ksr() must synchronize with the same process. Whoever
receives the first message (and no other process) must send a message
back to satisfy the receive. This reduces overhead in the daemon and
is within the constraints of client/server usage.
SEE ALSOkinit(2), nsend(2), nrecv(2)LAM 7.1.2 March, 2006 KSEND(2)