KSEND (2)
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 receiver is already waiting, blocked on
krecv() .
The reverse is also true.
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 below.
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.
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 message
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.
This field holds the length (in bytes) of the sender's message
or the receiver's buffer.
If the sender and the receiver specify 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() .
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 synchronization will never occur.
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 message 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 intervening period in the ready state.
This atomic transition from send to receive 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 other 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 ALSO
|