The message passing interface provides reliable unicast primitves. The primitives get as argument a pointer to a buffer. The len specifies the length of the data in the message that has to be sent. Every buffer has to reserve some space for a trailer that the message passing layer adds to the message (see pan_mp_trailer()).
int pan_mp_trailer(void);
Returns the space that the sender has to reserve for a trailer after the user data. The message passing layer uses this space to add information for demultiplexing. The data in the buffer where the trailer will be put may not be accessed during a call to send. The original data in this area is restored when the send call is finished.
typedef enum {PAN_MP_NORMAL, PAN_MP_DELAYED, PAN_MP_EXTERNAL} pan_mp_ack_t;
Describes the kind of acknowledgement that is required for a send operation. For the implementation on unreliable, this changes the communication behavior.
PAN_MP_NORMAL: Acknowledge message immediately PAN_MP_DELAYED: Try to acknowledge message with next message sent from the receiver. After a timeout, a normal acknowledgement is sent. PAN_MP_EXTERNAL:The message is acknowledged explicitly when the sender knows that the message must have arrived.
int pan_mp_send(int cpu, int port, void *data, int len, pan_mp_ack_t ack);
Sends message data with length len to the given destination. A destination consists of a platform id and a port number. This function returns a ticket, which must be used to synchronize on (see pan_mp_finish_send or pan_mp_ack_send).
void pan_mp_async_send(int ticket, void (*upcall)(void *arg), void *arg);
Send message asynchronously. Upcall function upcall will be called when the message is guaranteed to be delivered with arg as argument. It is not allowed to make calls to finish_send or poll_send with ticket as argument after this call.
void pan_mp_finish_send(int ticket);
Wait for send to finish. The message may not have been sent with PAN_MP_EXTERNAL. The ticket returned by pan_mp_send must be passed as parameter. It is not allowed to use ticket after this call.
int pan_mp_poll_send(int ticket);
Poll whether send is finished. The message may not have been sent with PAN_MP_EXTERNAL. The ticket returned by pan_mp_message_send must be passed as parameter. Returns 1 if ready, 0 otherwise. After the poll returns 1, ticket may not be used anymore.
void pan_mp_ack_send(int ticket);
Acknowledge a send operation. The message must have been sent with PAN_MP_EXTERNAL. The ticket returned by pan_mp_send must be passed as parameter.
#define PAN_MP_DIRECT_PORT 0
int pan_mp_receive(int port);
Receive a message. This function returns a ticket that must be used to synchronize on (see pan_mp_finish_receive). If a receive is done on PAN_MP_DIRECT_PORT, the ticket number serves as a one-time pseudoport number, and can be passed to other machines to address this receive call.
void *pan_mp_finish_receive(int ticket, int *size, int *len);
Wait for receive to finish. The ticket returned by pan_mp_receive must be passed as parameter. The function returns a message buffer with size size and length len, which must be cleared by the caller with pan_free. If the port is freed during the call to pan_mp_finish_receive, a NULL message is returned.
int pan_mp_poll_receive(int ticket);
Poll whether receive is finished. The ticket returned by pan_mp_receive must be passed as parameter. Returns 1 if ready, 0 otherwise.
void pan_mp_expect(int pid);
Tell the MP module that we expect a message from processor pid that should arrive soon. The MP module can use this as a hint. Experimental.
#endif /*__PAN_MP_H__
*/