Bulk Synchronous Message Passing

Collaboration diagram for Bulk Synchronous Message Passing:

Functions
void	bsp_set_tagsize (int *tag_nbytes)
void	bsp_send (int pid, const void *tag, const void *payload, int payload_nbytes)
void	bsp_hpsend (int pid, const void *tag, const void *payload, int payload_nbytes)
void	bsp_qsize (int *nmessages, int *accum_nbytes)
void	bsp_get_tag (int *status, void *tag)
void	bsp_move (void *payload, int reception_bytes)
int	bsp_hpmove (const void **tag_ptr, const void **payload_ptr)

Detailed Description

For irregular communication patterns, where processes don't know beforehand how much data they will receive from other processes, BSPlib provides also a way to communicate with messages.

As an example, below a small program where each process compiles a message, sends it to process 0, who then prints it to standard output. Note that process 0 doesn't need to know the length of the messages to process them.

#include <bsp.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
 
int main( int argc, char ** argv)
{
    bsp_pid_t s, root, p;
    bsp_nprocs_t P;
    char buffer[80];
    bsp_size_t payloadSize;
    const void * payload;
    const void * tag;
 
    // start the SPMD program
    bsp_begin( bsp_nprocs() );
 
    // store some short-hands
    root = 0;
    P = bsp_nprocs();
    s = bsp_pid();
 
    // prepare a message
    memset(buffer, 0, sizeof(buffer));
    payloadSize =
       snprintf(buffer, sizeof(buffer), "Hi, this is process %d\n", s);
    bsp_send(0, NULL, buffer, payloadSize);
    bsp_sync();
 
    // Let the root process the messages
    if (root == s)
    {
        payloadSize = bsp_hpmove( &payload, &tag );
        while ( bsp_size_unavailable != payloadSize )
        {
            int size = payloadSize;
            printf( "Received message: %.*s\n", size, payload );
            payloadSize = bsp_hpmove( &payload, &tag );
        }
    }
 
    // terminate the program
    bsp_end();
    return 0;
}

Function Documentation

bsp_set_tagsize()

void bsp_set_tagsize

(

int *

tag_nbytes

)

Set the tag size to be used by bsp_send() after the next bsp_sync(). All processes must call this function with the same value. The value of the parameter is overwritten with the current valid tag size. If this function is called multiple times in the same super-step, the value of the last call will be definitive.

Parameters

[in,out]

tag_nbytes

As input the size of tags as number of bytes after the next bsp_sync(). As output the tag size of the current superstep.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end().
bsp_abort	When tag_nbytes is negative

bsp_send()

void bsp_send	(	int	pid,
		const void *	tag,
		const void *	payload,
		int	payload_nbytes
	)

Send a message to a remote process which is guaranteed to have arrived after the next bsp_sync(). The payload and tag are copied before this function returns.

Parameters

[in]	pid	The ID of the destination process.
[in]	tag	A pointer to the tag to be send with the message. The tag size can be changed with a call to bsp_set_tagsize() in the preceding super-step, otherwise the tag size will remain the same. By default the tag size is 0.
[in]	payload	A pointer to the payload to be send with the message.
[in]	payload_nbytes	The size of the payload in bytes.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end().
bsp_abort	When payload_nbytes is negative

bsp_hpsend()

void bsp_hpsend	(	int	pid,
		const void *	tag,
		const void *	payload,
		int	payload_nbytes
	)

Send a message to a remote process which is guaranteed to have arrived after the next bsp_sync. The payload and tag are copied somewhere between the call of this function and the next bsp_sync().

Parameters

[in]	pid	The ID of the destination process.
[in]	tag	A pointer to the tag to be send with the message. The tag size can be changed with a call to bsp_set_tagsize() in the preceding super-step, otherwise the tag size will remain the same. By default the tag size is 0.
[in]	payload	A pointer to the payload to be send with the message.
[in]	payload_nbytes	The size of the payload in bytes.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end().
bsp_abort	When payload_nbytes is negative

bsp_qsize()

void bsp_qsize	(	int *	nmessages,
		int *	accum_nbytes
	)

Query the size of the message queue which have arrived at this process at the previous bsp_sync().

Parameters

[out]	nmessages	The number of messages in the queue
[out]	accum_nbytes	The total number of bytes in the payloads of messages in the queue.

Exceptions

bsp_abort

When not between bsp_begin() and bsp_end().

bsp_get_tag()

void bsp_get_tag	(	int *	status,
		void *	tag
	)

Get the tag size and the size of the payload of the first message in the message queue. The message queue consists of the messages that have arrived at this process at the previous bsp_sync() and haven't been dequeued yet. If the queue is empty, status is set to -1

Parameters

[out]	status	If the queue is non-empty the size of the payload of the first message in the queue. If the queue is empty, status is set to -1.
[out]	tag	A pointer to the memory area where this function can copy the message tag to. The size of this tag is the same as when the message was sent in the previous superstep.

Exceptions

bsp_abort

When not between bsp_begin() and bsp_end().

bsp_move()

void bsp_move	(	void *	payload,
		int	reception_bytes
	)

Dequeue the first message in the message queue and copy the payload to the specified place. The message queue consists of the messages that have arrived at this process at the previous bsp_sync() and haven't been dequeued yet.

Parameters

[out]	payload	A pointer to the memory where the payload should be copied to.
[in]	reception_bytes	The maximum amount of bytes to copy from the payload in to the memory designated by payload. This means that if the payload was actually larger, the payload will be truncated.

Exceptions

bsp_abort	When not between bsp_begin() and bsp_end().
bsp_abort	When reception_bytes is negative
bsp_abort	When the message queue is empty

bsp_hpmove()

int bsp_hpmove	(	const void **	tag_ptr,
		const void **	payload_ptr
	)

Dequeue the first message in the message queue and provide a pointer the payload and tag. The message queue consists of the messages that have arrived at this process at the previous bsp_sync() and haven't been dequeued yet.

Parameters

[out]	tag_ptr	The pointer where to copy the tag from. Note that the tag size is the same when it was sent in the previous superstep.
[out]	payload_ptr	The pointer where to copy the payload from.

Returns

The payload size, or -1 when the queue is empty.

Exceptions

bsp_abort

When not between bsp_begin() and bsp_end().