MulticoreBSP for C  Version 2.0.4
Functions
Bulk Synchronous Message Passing

Bulk Synchronous Message Passing (BSMP) provides message passing semantics to BSPlib programs. More...

Functions

static void bsp_set_tagsize (bsp_size_t *const size)
 Sets the tag size of inter-thread messages. More...
 
static void bsp_send (const bsp_pid_t pid, const void *const tag, const void *const payload, const bsp_size_t size)
 Sends a message to a remote thread. More...
 
static void bsp_hpsend (const bsp_pid_t pid, const void *const tag, const void *const payload, const bsp_size_t size)
 This is a non-buffering and non-blocking send request. More...
 
static void bsp_qsize (bsp_nprocs_t *const packets, bsp_size_t *const accumulated_size)
 Queries the size of the incoming BSMP queue. More...
 
static void bsp_get_tag (bsp_size_t *const status, void *const tag)
 Retrieves the tag of the first message in the queue of incoming messages. More...
 
static void bsp_move (void *const payload, const bsp_size_t max_copy_size)
 Retrieves the payload from the first message in the queue of incoming messages, and removes that message. More...
 
static bsp_size_t bsp_hpmove (void **const p_tag, void **const p_payload)
 Unbuffered retrieval of the payload of the first message in the incoming message queue. More...
 

Detailed Description

Bulk Synchronous Message Passing (BSMP) provides message passing semantics to BSPlib programs.

A message consists of a tag and a payload. The tag size is fixed during a superstep, while the payload size can vary per message.

To control the tag size (in bytes):

To send a message:

To inspect the queue of received messages:

To receive a message:

Function Documentation

static void bsp_get_tag ( bsp_size_t *const  status,
void *const  tag 
)
inlinestatic

Retrieves the tag of the first message in the queue of incoming messages.

Also retrieves the size of the payload in that message.

If there are no messages waiting in queue, status will be set to the maximum possible value and no tag data is retrieved.

Note: if MCBSP_COMPATIBILITY_MODE is defined, status is of type `int*', and *status will be set to -1 if there are no incoming messages. Otherwise, status is of type `unsigned int'.

Parameters
statusPointer to where to store the payload size (in bytes) of the first incoming message.
tagPointer to where to store the tag of the first incoming message.

References mcbsp_get_tag.

static bsp_size_t bsp_hpmove ( void **const  p_tag,
void **const  p_payload 
)
inlinestatic

Unbuffered retrieval of the payload of the first message in the incoming message queue.

The BSPlib implementation guarantees the returned memory areas remain valid during the current computation phase.

See bsp_move for general remarks. This function returns a pointer to an area in the incoming message buffer where the requested message tag and message payload reside. The function returns the size (in bytes) of the message payload.

If the BSMP queue is empty, this function will return SIZE_MAX and leave p_tag and p_payload as is.

Take care not to free the memory referred to by these pointers; the data resides in a MulticoreBSP-managed buffer area and will be freed by the BSP run-time system.

Warning: pointers obtained using this primitive will no longer be valid after the next bsp_sync.

Warning: use this high-performance function with care; out of bound access on tag or payload can easily cause segfaults.

Note: if MCBSP_COMPATIBILITY_MODE is defined, then (1) the return type of this function is `int' (instead of `size_t'), and (2) should the incoming message queue be empty, this function returns -1 instead of SIZE_MAX.

Parameters
p_tagWhere to store the pointer to the message tag. This parameter cannot equal NULL.
p_payloadWhere to store the pointer to the message payload. This parameter cannot equal NULL.
Returns
Size (in bytes) of the payload, or SIZE_MAX if the message queue was empty.

References mcbsp_hpmove.

static void bsp_hpsend ( const bsp_pid_t  pid,
const void *const  tag,
const void *const  payload,
const bsp_size_t  size 
)
inlinestatic

This is a non-buffering and non-blocking send request.

The function differs from the regular bsp_send in two major ways: (1) the actual send communication may occur between now and the end of the next synchronisation phase, and (2) the tag and payload data is read and sent somewhere between now and the end of the next synchronisation phase. If you change the contents of the memory areas corresponding to the tag and payload pointers before the next bsp_sync, the communication induced by this bsp_hpsend will be undefined.

The semantics of BSMP remain unchanged: the sent messages will only become available at the remote processor when the next computation superstep begins. The performance gain is two-fold: (a) bsp_hpsend avoids buffering-on-send, and (b) BSP may send messages during a computation phase, thus overlapping computation with communication. Ad (a): normally, BSMP in BSP copies tag and payload data at least three times. It buffers on bsp_send (buffer-on-send), it buffers at the receiving processes' incoming BSMP queue (buffer-on-receive), and finally bsp_get_tag and bsp_move copy the data in the target user-supplied memory areas. To also eliminate the latter data movement, please consider using bsp_hpmove. Ad (b): it is not guaranteed this overlap results in faster execution time. You should think about if using these high- performance primitives makes sense on a per-application basis, and factor in the extra costs of structuring your algorithm to enable correct use of these primitives.

See bsp_send for general remarks about using BSMP primitives in BSP. See bsp_hpget and bsp_hpput for equivalent (non- buffering and non-blocking) high-performance communication requests.

Note: If MCBSP_COMPATIBILITY_MODE is defined, then pid and size are of type `int'. Otherwise, pid is of type `unsigned int' and size of type `size_t'.

Parameters
pidID of the receiving thread.
tagPointer to the tag data (actual data is not buffered)
payloadPointer to the payload data. (actual data is not buffered)
sizeSize of the payload data (in bytes).
Remarks
This function first appeared in MulticoreBSP for C by Yzelman et al. (2014). It is not an original BSPlib primitive as defined by Hill et al. (1998).

References mcbsp_hpsend.

static void bsp_move ( void *const  payload,
const bsp_size_t  max_copy_size 
)
inlinestatic

Retrieves the payload from the first message in the queue of incoming messages, and removes that message.

If the incoming queue is empty, this function has no effect. This function will copy a given maximum of bytes from the message payload into a supplied buffer. This maximum should equal or be larger than the payload size (which can, e.g., be retrieved via bsp_get_tag). The maximum can be 0 bytes; the net effect is the efficient removal of the first message from the queue.

Note that BSMP (BSMP) is doubly buffered: bsp_send buffers on send and this function buffers again on receives.

See bsp_hpmove if buffer-on-receive is unwanted.

Note: if MCBSP_COMPATIBILITY_MODE is defined, max_copy_size is of type `int'. Otherwise, it is of type `size_t'.

Parameters
payloadWhere to copy the message payload into.
max_copy_sizeThe maximum number of bytes to copy.

References mcbsp_move.

static void bsp_qsize ( bsp_nprocs_t *const  packets,
bsp_size_t *const  accumulated_size 
)
inlinestatic

Queries the size of the incoming BSMP queue.

Parameters
packetsWhere to store the number of incoming messages.
accumulated_sizeWhere to store the accumulated size of all incoming messages (optional, can be NULL).

References mcbsp_qsize.

static void bsp_send ( const bsp_pid_t  pid,
const void *const  tag,
const void *const  payload,
const bsp_size_t  size 
)
inlinestatic

Sends a message to a remote thread.

A message is actually a tuple (tag,payload). Tag is of a fixed size (see bsp_set_tagsize), the payload size is set per message. Messages will be available at the destination thread in the next superstep.

Note: If MCBSP_COMPATIBILITY_MODE is defined, then pid and size are of type `int'. Otherwise, pid is of type `unsigned int' and size of type `size_t'.

Parameters
pidID of the remote thread to send this message to.
tagPointer to the tag data.
payloadPointer to the payload data.
sizeSize of the payload data (in bytes).

References mcbsp_send.

static void bsp_set_tagsize ( bsp_size_t *const  size)
inlinestatic

Sets the tag size of inter-thread messages.

bsp_send can be used to send message tuples (tag,payload). Tag must be of a fixed size, the payload size may differ per message.

This function sets the tagsize to the given size. This new size will be valid from the next bsp_sync() on. All processes must call bsp_set_tagsize with the same new size, or MulticoreBSP for C will return an error.

The given size will be overwritten with the currently active tagsize upon function exit, where `currently active' means the tag size as expected by BSP if bsp_send were executed during this superstep.

Note: if MCBSP_COMPATIBILITY_MODE is defined, size is of type `int*'. Otherwise, it is of type `size_t*'.

Parameters
sizePointer to the new tag size (in bytes). On exit, the memory area pointed to is changed to reflect the old tag size.

References mcbsp_set_tagsize.