fluke_error_t fluke_ipc_side_receive( fluke_ipc_params_t *ipc_params);
This function receives data words and references across one of the current thread's reliable IPC connections. A client thread uses fluke_ipc_client_receive to receive data from its server, while a server thread uses fluke_ipc_server_receive to receive data from its current client.The calling thread receives data, waiting if necessary, until the supplied buffer for at least one of the data types (simple data or references) becomes full or until the sender reverses or breaks the connection. If all of the data buffers or all of the references are filled, then this function returns and the receiver must create more room and then make another call to this function to continue receiving.
After the receive buffer for one data type fills up, the receiver may or may not be able to continue receiving data of the other type before emptying the full receive buffer. In other words, Fluke implementations (and any intermediaries interposed on the IPC channel) may treat the two data types as independent parallel streams, or they may impose some relative ordering between the streams. Thus, for example, a receiver can't expect to be able to receive all the items of one data type, followed by all the items of another in a separate ``phase''; the receiver must accept whatever is sent, when it is sent, if it is to receive at all.
By implication, if the receiver provides one or more data buffers but no reference objects to receive into, or one or more reference objects but no data buffers, then this call may return immediately without transferring anything if the sender is trying to send one or more instances of the data type for which the receiver did not supply a receive buffer. The receiver must create an appropriate buffer and reinvoke the receive operation in order to receive further data of either type.
For references, the provided receive reference table must contain pointers to valid reference objects created with fluke_ref_create. The existing reference objects will be modified to be equivalent to the corresponding references sent by the sender. The reference objects themselves are not transferred; their contents is merely copied from the sender's reference object to the receiver's.
- 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.
Returns one of the following codes: All of these have an implicit FLUKE_ prefix.
- SUCCESS
- The sender has finished sending message data and is attempting to reverse the transfer direction. The other side is now ready to reverse the connection again. The caller (receiver) must perform an ack_send operation to complete the reversal and initiate data transfer in the other direction.
- IPC_RECV_MORE_DATA
- All of the provided data buffers filled up before the sender finished transferring its first message. The caller must make more room for incoming data and use fluke_ipc_side_receive to receive it. The ipc_params structure is updated appropriately to indicate the amount of data received.
- IPC_RECV_MORE_REFS
- All of the provided references were filled before the sender finished transferring its first message. The caller must make room for more references and use fluke_ipc_side_receive to receive them. The ipc_params structure is updated appropriately to indicate the number of references received.
- IPC_RECV_DISCONNECTED
- 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.
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.
- NOT_RECEIVER
- The current thread is not the receiver on the specified IPC connection.
- NO_OBJECT
- A pointer in the ipc_params receive reference array does not refer to an active object.
- NOT_REF
- An object in the ipc_params receive reference array is not a reference object.
- INVALID_OBJECT
- 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.
fluke_ipc_side_send