bps_channel_exec()

#include <bps/bps.h>
 

BPS_API int bps_channel_exec(int chid,
                             int(*exec)(void *),
                             void *data)

Since:

BlackBerry 10.0.0

Arguments:

chid

The channel ID designating which channel event queue to enqueue the exec callback.

exec

The function that will be executed. The first argument to the callback will be the data that is passed to bps_channel_exec() function. Any returned result will be ignored.

data

The user data that will be used as the first argument of the invoke function.

Library:

libbps (For the qcc command, use the -l bps option to link against this library)

Description:

Calling bps_channel_exec() registers the provided function by creating an exec event, which is an event that combines the function and the specified data. The function is referred to as the exec function, although it can also be thought of as a callback function. The exec event is added to the event queue of the destination channel (chid). The exec function is invoked with the provided data during a call to bps_get_event() when the exec event is removed from the event queue. Note that the caller of bps_get_event() will not receive this exec event; it is consumed by BPS and converted into a call to the exec function.

The bps_channel_exec() function works across threads. The channel chid can be owned by the same thread that is calling bps_channel_exec() or by an entirely different thread. When performing a cross-thread exec, care must be taken to safe-guard any data that is shared between the calling thread and the thread that owns the destination channel chid. The same precautions should be taken with the use of the data argument.

Returns:

BPS_SUCCESS if the invoke callback was successfully registered with channel chid. BPS_FAILURE if registration failed. errno will be set to the cause of failure.