Multicast interface

Provide abstraction to multicast data to several nodes in a dynamic fashion: More...

typedef struct nm_mcast_service_s *	nm_mcast_service_t
	Public abstraction for a mcast service.
typedef void(*	nm_mcast_send_notifier_t) (void *p_ref)
	Public abstraction for the callback called when the mcast_send is completed.
typedef struct nm_mcast_req_s	nm_mcast_t
	Public abstraction for nm_mcast_req_s.
nm_mcast_service_t	nm_mcast_init (nm_comm_t p_comm)
	Initializes the mcast interface.
void	nm_mcast_finalize (nm_mcast_service_t nm_mcast)
	Release the mcast interface.
void	nm_mcast_send (nm_mcast_service_t nm_mcast, nm_comm_t p_recv_comm, int *p_dests, int *p_prios, int n_dests, nm_tag_t tag, struct nm_data_s *p_data, nm_len_t hlen, nm_coll_tree_kind_t tree_kind)
	Send data in a blocking mode.
void	nm_mcast_send_init (nm_mcast_service_t nm_mcast, nm_mcast_t *p_mcast)
	Initialize a multicast send.
void	nm_mcast_send_set_notifier (nm_mcast_t *p_mcast, nm_mcast_send_notifier_t notifier, void *p_ref)
	Attach a notifier to mcast_send, to be called when the root node of the multicast ends its sends.
void	nm_mcast_isend (nm_mcast_t *p_mcast, nm_comm_t p_comm, int *p_dests, int *p_prios, int n_dests, nm_tag_t tag, struct nm_data_s *p_data, nm_len_t hlen, nm_coll_tree_kind_t tree_kind)
	Send data in a non-blocking mode.
void	nm_mcast_wait (nm_mcast_t *p_mcast)
	Wait for a non-blocking multicast send.
void	nm_mcast_send_destroy (nm_mcast_t *p_mcast)
	Free data allocated by nm_mcast_send_init()
void	nm_mcast_set_default_tree_kind (nm_mcast_service_t nm_mcast, const nm_coll_tree_kind_t kind)
	Change the default tree used for routing data.

Detailed Description

Provide abstraction to multicast data to several nodes in a dynamic fashion:

• only sender node has to know all the recipient nodes,
• no need to build a communicator containing all recipients of the the multicast,

• whatever the way data was sent (with a point-to-point send or a multicast), it will be transparent for receivers: they just have to use a regular point-to-point receive function.

  Basic use:

  1. Initialize the interface by calling nm_mcast_init()
  2. Send multicasts with nm_mcast_*send() functions
  3. Receive data as if the data will come from a regular point-to-point exchange: with a nm_sr_recv() function. Be sure to use the session of the communicator used in nm_mcast_send().
  4. Shutdown the interface by calling nm_mcast_finalize()

See examples/mcast/nm_mcast_basic.c for a basic example.

Three types of tree can be used for multicasting: binomial, binary or chained trees. Binomial tree is the default scheme. You can set the default type of tree to use by calling nm_mcast_set_default_tree_kind() of by defining the environment variable NMAD_MCAST_TREE to binary, binomial or chain. Moreover you can change the type of tree directly when calling nm_mcast_send().

Typedef Documentation

nm_mcast_send_notifier_t

typedef void(* nm_mcast_send_notifier_t) (void *p_ref)

Public abstraction for the callback called when the mcast_send is completed.

Definition at line 59 of file nm_mcast_interface.h.

nm_mcast_service_t

typedef struct nm_mcast_service_s* nm_mcast_service_t

Public abstraction for a mcast service.

Definition at line 56 of file nm_mcast_interface.h.

nm_mcast_t

typedef struct nm_mcast_req_s nm_mcast_t

Public abstraction for nm_mcast_req_s.

Definition at line 72 of file nm_mcast_interface.h.

Function Documentation

nm_mcast_finalize()

void nm_mcast_finalize

(

nm_mcast_service_t

nm_mcast

)

Release the mcast interface.

Examples

nm_mcast_basic.c.

nm_mcast_init()

nm_mcast_service_t nm_mcast_init

(

nm_comm_t

p_comm

)

Initializes the mcast interface.

Parameters

p_comm

communicator used for the RPC service for mcast

Examples

nm_mcast_basic.c.

nm_mcast_isend()

void nm_mcast_isend	(	nm_mcast_t *	p_mcast,
		nm_comm_t	p_comm,
		int *	p_dests,
		int *	p_prios,
		int	n_dests,
		nm_tag_t	tag,
		struct nm_data_s *	p_data,
		nm_len_t	hlen,
		nm_coll_tree_kind_t	tree_kind
	)

Send data in a non-blocking mode.

Parameters

p_mcast

has to initialized with nm_mcast_send_init(). See nm_mcast_send() for details about other parameters.

nm_mcast_send()

void nm_mcast_send	(	nm_mcast_service_t	nm_mcast,
		nm_comm_t	p_recv_comm,
		int *	p_dests,
		int *	p_prios,
		int	n_dests,
		nm_tag_t	tag,
		struct nm_data_s *	p_data,
		nm_len_t	hlen,
		nm_coll_tree_kind_t	tree_kind
	)

Send data in a blocking mode.

Parameters

nm_mcast	a mcast service initiliazed with nm_mcast_init().
p_recv_comm	a communicator (must be the same as the one used by the nm_sr_recv).
p_dests	an array of ranks which are recipients of the multicast. This array can be a subset of the communicator p_comm.
p_prios	an array providing priorities for each recipient. Can be set to NULL. To respect priorities, prios has to be sorted in descending order (and array dests ordered such as prios[i] is the priority of the send to the node dests[i]). Higher is the integer, higher is the priority.
n_dests	the number of recipients of the multicast (size of the array dests).
tag	the message tag.
p_data	iterator on the data to send, the memory targeted by this pointer has to be valid until the mcast ends.
hlen	size of the user header.
tree_kind	type of tree to broadcast the data. If the user provides NM_COLL_TREE_DEFAULT, the type set by nm_mcast_set_default_tree_kind() will be used.

Examples

nm_mcast_basic.c.

nm_mcast_send_destroy()

void nm_mcast_send_destroy

(

nm_mcast_t *

p_mcast

)

Free data allocated by nm_mcast_send_init()

nm_mcast_send_init()

void nm_mcast_send_init	(	nm_mcast_service_t	nm_mcast,
		nm_mcast_t *	p_mcast
	)

Initialize a multicast send.

Useful to then wait the end of the multicast send or to set a callback. To be released with nm_mcast_send_destroy().

nm_mcast_send_set_notifier()

void nm_mcast_send_set_notifier	(	nm_mcast_t *	p_mcast,
		nm_mcast_send_notifier_t	notifier,
		void *	p_ref
	)

Attach a notifier to mcast_send, to be called when the root node of the multicast ends its sends.

nm_mcast_set_default_tree_kind()

void nm_mcast_set_default_tree_kind	(	nm_mcast_service_t	nm_mcast,
		const nm_coll_tree_kind_t	kind
	)

Change the default tree used for routing data.

It will be the rooting algorithm used if the user provides NM_COLL_TREE_DEFAULT to nm_mcast_*send functions.

nm_mcast_wait()

void nm_mcast_wait

(

nm_mcast_t *

p_mcast

)

Wait for a non-blocking multicast send.