Events and Triggered Operations

Functions
ucc_status_t	ucc_ee_create (ucc_team_h team, const ucc_ee_params_t *params, ucc_ee_h *ee)
	The routine creates the execution context for collective operations. More...
ucc_status_t	ucc_ee_destroy (ucc_ee_h ee)
	The routine destroys the execution context created for collective operations. More...
ucc_status_t	ucc_ee_get_event (ucc_ee_h ee, ucc_ev_t **ev)
	The routine gets the event from the event queue. More...
ucc_status_t	ucc_ee_ack_event (ucc_ee_h ee, ucc_ev_t *ev)
	The routine acks the events from the event queue. More...
ucc_status_t	ucc_ee_set_event (ucc_ee_h ee, ucc_ev_t *ev)
	The routine to set the event to the tail of the queue. More...
ucc_status_t	ucc_ee_wait (ucc_ee_h ee, ucc_ev_t *ev)
	The routine blocks the calling thread until there is an event on the queue. More...
ucc_status_t	ucc_collective_triggered_post (ucc_ee_h ee, ucc_ev_t *ee_event)
	The routine posts the collective operation on the execution engine, which is launched on the event. More...

Detailed Description

Event-driven Collective Execution

Function Documentation

ucc_ee_create()

ucc_status_t ucc_ee_create	(	ucc_team_h	team,
		const ucc_ee_params_t *	params,
		ucc_ee_h *	ee
	)

Parameters

[in]	team	team handle
[in]	params	user provided params to customize the execution engine
[out]	ee	execution engine handle

Description

ucc_ee_create creates the execution engine. It enables event-driven collective execution. ucc_ee_params_t allows the execution engine to be configured to abstract either GPU and CPU threads. The execution engine is created and coupled with the team. There can be many execution engines coupled to the team. However, attaching the same execution engine to multiple teams is not allowed. The execution engine is created after the team is created and destroyed before the team is destroyed. It is the user's responsibility to destroy the execution engines before the team. If the team is destroyed before the execution engine is destroyed, the result is undefined.

Returns

Error code as defined by ucc_status_t

ucc_ee_destroy()

ucc_status_t ucc_ee_destroy

(

ucc_ee_h

ee

)

Parameters

[in]

ee

Execution engine handle

Description

ucc_ee_destroy releases the resources attached with the execution engine and destroys the execution engine. All events and triggered operations related to this ee are invalid after the destroy operation. To avoid race between the creation and destroying the execution engine, for a given ee, the ucc_ee_create and ucc_ee_destroy must be invoked from the same thread.

Returns

Error code as defined by ucc_status_t

ucc_ee_get_event()

ucc_status_t ucc_ee_get_event	(	ucc_ee_h	ee,
		ucc_ev_t **	ev
	)

Parameters

[in]	ee	execution engine handle
[out]	ev	Event structure fetched from the event queue

Description

ucc_ee_get_event fetches the events from the execution engine. If there are no events posted on the ee, it returns immediately without waiting for events. All events must be acknowledged using the ucc_ee_ack_event interface. The event acknowledged is destroyed by the library. An event fetched with ucc_ee_get_event but not acknowledged might consume resources in the library.

Returns

Error code as defined by ucc_status_t

ucc_ee_ack_event()

ucc_status_t ucc_ee_ack_event	(	ucc_ee_h	ee,
		ucc_ev_t *	ev
	)

Parameters

[in]	ee	execution engine handle
[in]	ev	Event to be acked

Description

An event acknowledged by the user using ucc_ee_ack_event is destroyed by the library. Any triggered operations on the event should be completed before calling this interface. The behavior is undefined if the user acknowledges the event while waiting on the event or triggering operations on the event.

Returns

Error code as defined by ucc_status_t

ucc_ee_set_event()

ucc_status_t ucc_ee_set_event	(	ucc_ee_h	ee,
		ucc_ev_t *	ev
	)

Parameters

[in]	ee	execution engine handle
[in]	ev	Event structure fetched from the event queue

Description

ucc_ee_set_event sets the event on the execution engine. If the operations are waiting on the event when the user sets the event, the operations are launched. The events created by the user need to be destroyed by the user.

Returns

Error code as defined by ucc_status_t

ucc_ee_wait()

ucc_status_t ucc_ee_wait	(	ucc_ee_h	ee,
		ucc_ev_t *	ev
	)

Parameters

[in]	ee	execution engine handle
[out]	ev	Event structure fetched from the event queue

Description

The user thread invoking the ucc_ee_wait interface is blocked until an event is posted to the execution engine.

Returns

Error code as defined by ucc_status_t

ucc_collective_triggered_post()

ucc_status_t ucc_collective_triggered_post	(	ucc_ee_h	ee,
		ucc_ev_t *	ee_event
	)

Parameters

[in]	ee	execution engine handle
[in]	ee_event	Event triggering the post operation

Description

ucc_collective_triggered_post allow the users to schedule a collective operation that executes in the future when an event occurs on the execution engine.

Returns

Error code as defined by ucc_status_t