8.6 fluke_ipc_client_connect_send_over_receive: perform a reliable RPC to a server

SYNOPSIS

fluke_error_t fluke_ipc_client_connect_send_over_receive(fluke_ref_t *destination, fluke_ipc_params_t *ipc_params);

DESCRIPTION

This function is a combination of fluke_ipc_client_connect_send and fluke_ipc_client_over_receive. It establishes a reliable IPC connection with a server thread, sends some data and/or references to the server, then reverses the connection and waits to receive data from the server. This call is the standard client-side interface for reliable RPC mechanisms.

PARAMETERS

destination

A pointer to a port reference indicating the port to invoke.

ipc_params

A pointer to a structure describing data and references to send, and the buffers and references to receive the response into. Only the receive parameter fields are modified by the call.

RETURNS

Returns one of the following codes: All of these have an implicit FLUKE_ prefix.

SUCCESS

The connection has been established, all data indicated by the send parameters in ipc_params has been sent, and a reply was received into the buffers indicated by the receive parameters in ipc_params.

IPC_CONNECT_INVALID_DEST

The IPC target referenced by destination is invalid, e.g. because the port it refers to was destroyed or the server task was terminated. Note that if the IPC destination is invalid, it is unspecified whether this condition will be detected at connection time by this function, or at a later stage such as the first send or receive. Application code must in general be prepared to handle error conditions detected at any time during communication.

IPC_SEND_DISCONNECTED

The connection was successfully established, but it was broken while sending the data and references specified.

IPC_OVER_DISCONNECTED

The IPC connection was established, but was broken while trying to reverse the connection.

IPC_RECV_MORE_DATA

During the receive phase, all of the provided data buffers filled up before the server finished transferring its first message. The caller must make more room for incoming data and use fluke_ipc_client_receive to receive it. The ipc_params structure is updated appropriately to indicate the amount of data received.

IPC_RECV_MORE_REFS

During the receive phase, all of the provided references were filled before the server finished transferring its first message. The caller must make room for more references and use fluke_ipc_client_receive to receive them. The ipc_params structure is updated appropriately to indicate the number of references received.

IPC_RECV_DISCONNECTED

During the receive phase, the sender disconnected after sending some data but before the receiver's buffers were filled. The ipc_params structure is updated appropriately to indicate the amount of data and references received. This return code often indicates normal connection termination.

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 destination. A pointer in either the ipc_params send or receive reference array does not refer to an active object.

NOT_REF

The object at destination is not a reference object. An object in either the ipc_params send or receive reference array is not a reference object.

NOT_PORT_REF

The object at destination is a reference object, but not a reference to a port.

INVALID_OBJECT

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

BUFFER_TOO_SMALL

The initial send data was smaller than FLUKE_MIN_MSG_SIZE.

BUFFER_UNALIGNED

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

RELATED INFORMATION

fluke_ipc_client_send, fluke_ipc_client_receive, fluke_ipc_client_over, fluke_ipc_client_disconnect, fluke_ipc_wait_receive