8.12 fluke_ipc_setup_wait_receive: set up a server thread and wait for incoming IPC invocations

SYNOPSIS

fluke_ipc_error_t fluke_ipc_setup_wait_receive(fluke_pset_t *pset, fluke_ipc_params_t *ipc_params, void **port_alias);

DESCRIPTION

This function initializes a thread's server-side IPC state, including the port set the server thread is attached to, and then puts the server thread to sleep waiting for an incoming IPC request on that port set. Later, the thread can wait for subsequent messages on the same port set using fluke_ipc_wait_receive or one of the combination operations that includes a wait_receive.

PARAMETERS

pset

The port set on which the server thread should wait for incoming IPC invocations.

ipc_params

A pointer to a structure describing data buffers and reference objects to receive information into. Only the receive parameter fields in this structure are used; the send parameter fields are ignored.

port_alias

When an incoming IPC request is successfully received, this pointer is set to the port alias attached to the port through which the IPC invocation was made, allowing the server to distinguish requests to different ports that are attached to a single port set.

RETURNS

This function returns a status code providing information about the received IPC invocation. All of these have an implicit FLUKE_ prefix.

SUCCESS

If this was a reliable invocation, a reliable IPC connection was established, and the entire initial message from the client was received into the the server's receive buffers and references. For oneway or idempotent invocations, either the entire message or as much as would fit in the server's buffers was received. For all cases, the ipc_params structure is updated appropriately to indicate the amount of data and references received.

IPC_RECV_MORE_DATA

A reliable IPC connection was established, but all of the provided receive data buffers filled up before the client finished transferring its first message. The caller must make more room for incoming data and use fluke_ipc_server_receive to receive it. The ipc_params structure is updated appropriately to indicate the amount of data received.

IPC_RECV_MORE_REFS

A reliable IPC connection was established, but all of the provided receive references were filled before the client finished transferring its first message. The caller must make room for more references and use fluke_ipc_server_receive to receive them. The ipc_params structure is updated appropriately to indicate the number of references received.

IPC_RECV_DISCONNECTED

A reliable IPC connection was established, but the sender disconnected after sending some data but before the caller's receive buffers were filled. The ipc_params structure is updated appropriately to indicate the amount of data and references received.

IPC_WAIT_ONEWAY

A one-way message was received. The caller merely needs to process the message and then wait for more messages if appropriate; no response of any kind is required.

IPC_WAIT_IDEMPOTENT

An idempotent message was received. The caller should process the message and then reply to it using fluke_ipc_reply.

ERRORS

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes. All of these have an implicit FLUKE_INSANITY_ prefix.

NO_OBJECT

No active object was found at pset. A pointer in the ipc_params receive reference array does not refer to an active object.

NOT_PSET

The object pointed to by pset is not a port set object.

NOT_REF

An object in the ipc_params receive reference array is not a reference object.

INVALID_OBJECT

The state of the object at pset is invalid or the state of an object in the ipc_params receive reference array is invalid.

BUFFER_UNALIGNED

A message buffer was not aligned properly according to the architecture-specific requirements.

RELATED INFORMATION

fluke_ipc_wait_receive