Bulk Synchronous Message Passing API

Collaboration diagram for Bulk Synchronous Message Passing API:

Classes
struct	lpf_bsmp_buffer

Enumerations
enum	lpf_bsmp_mode { READ , WRITE }

Functions
lpf_err_t	lpf_bsmp_create (const lpf_t ctx, const lpf_pid_t s, const lpf_pid_t p, const size_t buffer_size, const size_t tag_size, const size_t max_messages, lpf_bsmp_t *const bsmp)
lpf_err_t	lpf_bsmp_destroy (lpf_bsmp_t *const bsmp)
lpf_err_t	lpf_send (const lpf_bsmp_t bsmp, const lpf_pid_t pid, const lpf_memslot_t tag, const size_t tag_offset, const lpf_memslot_t payload, const size_t payload_offset, const size_t payload_size)
lpf_err_t	lpf_bsmp_sync (lpf_bsmp_t bsmp, lpf_sync_attr_t hint)
lpf_err_t	lpf_bsmp_syncall (lpf_bsmp_t *const bsmp, const size_t num_objects, lpf_sync_attr_t hint)
lpf_err_t	lpf_move (lpf_bsmp_t bsmp, void **const tag_p, void **const payload_p, size_t *const size)

Variables
typedef	lpf_bsmp_t
const lpf_bsmp_t	LPF_INVALID_BSMP
const lpf_err_t	LPF_ERR_BSMP_FULL
const lpf_err_t	LPF_ERR_BSMP_INVAL
const size_t	LPF_INVALID_SIZE
const lpf_memslot_t	LPF_INVALID_MEMSLOT

Detailed Description

Enumeration Type Documentation

lpf_bsmp_mode

enum lpf_bsmp_mode

A BSMP object can have one of the following modes at any single superstep.

Enumerator
READ	A BSMP object that has this mode can only be read from during the current superstep. After a next call to lpf_bsmp_sync the mode switches to WRITE. If the next call to lpf_sync precedes that of a next call to lpf_bsmp_sync, then the mode of a BSMP object shall not change.
WRITE	A BSMP object that has this mode can only be written to during the current superstep. After a next call to lpf_bsmp_sync the mode switches to READ. If the next call to lpf_sync precedes that of a next call to lpf_bsmp_sync, then the mode of a BSMP object shall not change.

Function Documentation

lpf_bsmp_create()

lpf_err_t lpf_bsmp_create	(	const lpf_t	ctx,
		const lpf_pid_t	s,
		const lpf_pid_t	p,
		const size_t	buffer_size,
		const size_t	tag_size,
		const size_t	max_messages,
		lpf_bsmp_t *const	bsmp
	)

Creates a new BSMP object. A successful call to this function will create a new BSMP object that is initially in WRITE mode.

Parameters

[in]	ctx	A valid LPF context.
[in]	s	This process ID in the context of ctx.
[in]	p	The total number of processes running in the context of ctx.
[in]	buffer_size	The maximum number of payload bytes that can be received or sent during any single superstep.
[in]	tag_size	The number of bytes each message contains in its tag. Contrary to the payload of a single message, the tag is always of the same size defined by this value.
[in]	max_messages	The maximum number of messages this BSMP object sends or receives during any single superstep.
[out]	bsmp	Where the resulting BSMP object should be stored.

Returns

LPF_SUCCESS When BSMP object creation completed successfully.

LPF_ERR_OUT_OF_MEMORY When not enough memory could be allocated to create a new BSMP object of the requested size. When this is returned, bsmp will be set to LPF_INVALID_BSMP while any successful memory allocations are reverted; other than setting an invalid bsmp it will be as though the call to this function was never made.

LPF usage.

A call to this function

1. registers four memory slots.
2. schedules zero messages to be sent.
3. expects to receive zero messages.
4. calls lpf_sync once (for memory registration).

lpf_bsmp_destroy()

lpf_err_t lpf_bsmp_destroy

(

lpf_bsmp_t *const

bsmp

)

Destroys a valid BSMP object. After a successful call to this function, the given queue is set to LPF_INVALID_BSMP.

Parameters

[in,out]

bsmp

The BSMP object to destroy.

Warning

If bsmp on input does not correspond to a valid BSMP object, undefined behaviour will occur.

Returns

LPF_SUCCESS This function never fails.

Note

This relies on the specification of lpf_deregister which also always succeeds.

LPF usage.

A call to this function

1. de-registers four LPF memory slots.
2. schedules zero messages to be sent.
3. expects to receive zero messages.
4. does not call lpf_sync.

lpf_send()

lpf_err_t lpf_send	(	const lpf_bsmp_t	bsmp,
		const lpf_pid_t	pid,
		const lpf_memslot_t	tag,
		const size_t	tag_offset,
		const lpf_memslot_t	payload,
		const size_t	payload_offset,
		const size_t	payload_size
	)

Given a local BSMP buffer, schedule a message for being sent to a remote BSMP object.

Parameters

[in]	bsmp	A valid BSMP object that is in WRITE mode.
[in]	pid	The destination process.
[in]	tag	The locally or globally registered memory slot from which to read the message tag.
[in]	tag_offset	The offset from the memory slot tag which indicates where the tag data resides.
[in]	payload	The locally or globally registered memory slot from which to read the message payload.
[in]	payload_offset	The offset from the memory slot payload which indicates where the payload data resides.
[in]	payload_size	The size (in bytes) of the payload data.

Warning

When bsmp does not correspond to a valid BSMP object, undefined behaviour will occur.

When passing a valid bsmp object that is not in WRITE mode, undefined behaviour will occur.

Returns

LPF_SUCCESS When the messages was successfully queued.

LPF_ERR_BSMP_INVAL When the BSMP object is in an invalid state. In this case the next call using bsmp that may succeed is one to lpf_bsmp_sync. The call to this function has no other effects; in particular, the given message will not be scheduled.

LPF_ERR_BSMP_FULL When the BSMP queue is full. In this case it will be as though this call was never made.

LPF usage.

A call to this function

1. registers zero LPF memory slots.
2. schedules three messages to be sent.
3. expects to receive zero messages.
4. does not call lpf_sync.

lpf_bsmp_sync()

lpf_err_t lpf_bsmp_sync	(	lpf_bsmp_t	bsmp,
		lpf_sync_attr_t	hint
	)

A wrapper around the regular lpf_sync. This wrapper additionally switches the mode of the given bsmp object; i.e., a BSMP object in read mode will be in write mode after a call to this function, and vice versa.

Parameters

[in]	bsmp	A valid BSMP object to switch the state of.
[in]	hint	The lpf_sync_attr_t that should be passed to the lpf_sync on the LPF context bsmp was created with.

If bsmp was in READ mode, then after the call to this function bsmp shall be in WRITE mode. All messages that are currently in the buffer will become unavailable. If bsmp was in WRITE mode, then after the call to this function bsmp shall be in READ mode. All messages that were ready to send out will be made available at the sibling processes after a successful call to this function. Messages send to this process by sibling processes will be readable by successive calls to lpf_move after the call to this function.

Returns

LPF_SUCCESS On successful switching

LPF_ERR_FATAL If the underlying call to lpf_sync fails. The state of the BSMP object will become invalid after this error is returned. The state of the LPF core library is undefined and should no longer be relied upon.

See also

lpf_sync for full details on the other effects of a call to this function.

LPF usage.

A call to this function

1. registers zero LPF memory slots.
2. schedules P messages to be sent.
3. expects to receive P messages, plus three more messages per BSMP message directed to this process. This number, while unknown, is bounded by the value of max_messages which was used to create the given bsmp object.
4. does call lpf_sync exactly once.

lpf_bsmp_syncall()

lpf_err_t lpf_bsmp_syncall	(	lpf_bsmp_t *const	bsmp,
		const size_t	num_objects,
		lpf_sync_attr_t	hint
	)

A wrapper around the regular lpf_sync. This wrapper additionally switches the mode of all lpf_bsmp_t objects in the given array bsmp. This function is semantically equivalent to the following implementation:

lpf_err_t lpf_bsmp_syncall( lpf_bsmp_t * const bsmp, const size_t num_objects,
                            lpf_sync_attr_t hint ) {
    for( size_t i = 0; i < num_objects; ++i ) {
        lpf_bsmp_sync( bsmp[ i ], hint );
    }
}

This function call is preferred since all preamble and postamble bookkeeping on bsmp objects is fused, requiring a single call to lpf_sync to be made, instead of num_objects calls to lpf_sync as in the above example.

Parameters

[in]	bsmp	Pointer to an array of num_objects lpf_bsmp_t objects. All objects must be valid.
[in]	num_objects	The number of lpf_bsmp_t objects in the array pointed to by num_objects.
[in]	hint	The hint to lpf_sync that will be passed to the internal call to lpf_sync.

See also

lpf_bsmp_sync For the exact behaviour on each single BSMP object in bsmp.

LPF usage.

A call to this function

1. registers zero LPF memory slots.
2. schedules \( \mathit{num\_objects} \cdot P \) messages to be sent.
3. expects to receive \( \mathit{num\_objects} \cdot P \) messages, plus three more messages per BSMP message directed to this process. This number is bounded by max_messages used to create each BSMP object.
4. does call lpf_sync exactly once.

lpf_move()

lpf_err_t lpf_move	(	lpf_bsmp_t	bsmp,
		void **const	tag_p,
		void **const	payload_p,
		size_t *const	size
	)

Given a local BSMP buffer, retrieve a message from the incoming queue.

Parameters

[in]	bsmp	A valid BSMP object that is in READ mode.
[out]	tag_p	Where to store a pointer to the message tag data.
[out]	payload_p	Where to store a pointer to the message payload data.
[out]	size	Where to store the payload size (in bytes).

Messages that were sent to this process are received in an arbitrary order. Once a message has been retrieved using a call to this function, it is immediately removed from the queue. If the queue was empty while this function was called, the size will be set to LPF_INVALID_SIZE, while tag_p and payload_p will be set to NULL.

Returns

LPF_SUCCESS A call to this function always succeeds.

Warning

If bsmp was not valid or was not in READ mode, undefined behaviour will occur.

Variable Documentation

lpf_bsmp_t

typedef lpf_bsmp_t

The BSMP object type.

LPF_INVALID_BSMP

const lpf_bsmp_t LPF_INVALID_BSMP

extern

An invalid BSMP object type.

LPF_ERR_BSMP_FULL

const lpf_err_t LPF_ERR_BSMP_FULL

extern

A new error code that signals a full BSMP buffer error for lpf_send().

LPF_ERR_BSMP_INVAL

const lpf_err_t LPF_ERR_BSMP_INVAL

extern

A new error code that signals a corrupt BSMP buffer. If this error code is returned, further use of the corresponding lpf_bsmp_t object leads to undefined behaviour. A next call to lpf_bsmp_sync() will bring back the BSMP buffer in a valid state.

LPF_INVALID_SIZE

const size_t LPF_INVALID_SIZE

extern

A new size_t object that corresponds to an invalid size.

LPF_INVALID_MEMSLOT

const lpf_memslot_t LPF_INVALID_MEMSLOT

extern

A new lpf_memslot_t object that corresponds to an invalid memslot.