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 receiver 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 below.

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 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.

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 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().

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 synchronization 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 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
kinit(2), nsend(2), nrecv(2)