spe_event_handler

NAME

spe_event_handler_register - Register the application's interest in SPE events.

SYNOPSIS

#include <libspe2.h>

int spe_event_handler_register(spe_event_handler_ptr_t evhandler, spe_event_unit_t *event);

Parameters
evhandler	A pointer to the SPE event handler.
event	A pointer to an SPE event structure.

DESCRIPTION

Registers the application’s interest in SPE events as defined in the event structure.

This function requires that the SPE context spe in event has been created with event support, that is, the SPE_EVENTS_ENABLE flag has been set. Otherwise, it returns an error ENOTSUP.

RETURN VALUE

On success, 0 (zero) is returned.

EXIT STATUS

On error, -1 is returned and errno is set to indicate the error.

Possible errors include:

ESRCH	The specified SPE event handler is invalid.
EINVAL	The specified pointer to an SPE event structure or the SPE context specified in the SPE event structure is invalid
ENOTSUP	At least one of the requested events specified in events is not supported or invalid or the SPE context does not support events.
EFAULT	A runtime error of the underlying OS service occurred.

USAGE

The data structure spe_event_unit_t is defined as follows:

typedef struct spe_event_unit {
   unsigned int events;
   spe_context_ptr_t spe;
   spe_event_data_t data;
}  spe_event_unit_t;

The field events specifies a bitmask to request certain SPE events to be delivered to the application. Multiple events can be requested at once by using bit-wise OR.

The following events are supported:

SPE_EVENT_OUT_INTR_MBOX	Data is available in the SPU outbound interrupting mailbox. This event is generated, when the SPU has written at least one entry to the SPU outbound interrupting mailbox (see spe_out_intr_mbox_read).
SPE_EVENT_IN_MBOX	Data can now be written to the SPU inbound mailbox. This event is generated when the inbound mailbox is not full and signals that at least one message can be successfully written spe_in_mbox_write).
SPE_EVENT_TAG_GROUP	An SPU event tag group signaled completion (see spe_mfcio_tag_status_read).
SPE_EVENT_SPE_STOPPED	Program execution on the SPE has stopped. (see spe_stop_info_read).
SPE_EVENT_ALL_EVENTS	Interest in all defined SPE events, this corresponds to a bit-wise OR of all flags above.

The field spe is a pointer to an SPE context for which the events have to be registered.

The structure spe_event_unit contains a field data of type spe_event_data that is intended to hold user data. The value of this field will be returned to the application by spe_event_wait unmodified, whenever an event as specified here occurs.

typedef union spe_event_data {
     void *ptr;
     unsigned int u32;   
     unsigned long long u64;
 }   spe_event_data_t;

spe_event_handler_register