interface xdc.runtime.knl.ISync

Modules that require the user to pick a synchronization method, will request a Handle. Clients of such modules can pick a blocking ISync implementation or a non-blocking implementation.

This interface specifies two main functions signal and wait. These two functions are always used in pairs in modules that use ISync instances. The signal() function is used to signal completion of an activity. The wait() function will allow the module to block or poll for completion of the same activity.

ISync mandates that the sync mechanism be binary and not support counters. Although the wait() function seems meaningless in the case of non-blocking sync, it allows modules to be written generically and support all ISync implementations. For non-blocking ISync the wait() function will return WaitStatus_TIMEOUT to denote timeout.

const ISync.NO_WAIT

index URL

Used to specify no waiting

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

const UInt NO_WAIT = 0;

const ISync.Q_BLOCKING

index URL

Blocking quality

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

const Int Q_BLOCKING = 1;

DETAILS

Implementations with this "quality" may cause the calling thread to block;

const ISync.WAIT_FOREVER

index URL

Used to wait forever

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

const UInt WAIT_FOREVER = ~(0);

enum ISync.WaitStatus

index URL

Error codes returned by ISync_wait

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

enum WaitStatus {

WaitStatus_ERROR,

WaitStatus_TIMEOUT,

WaitStatus_SUCCESS

};

metaonly config ISync.common$ // module-wide

index URL

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

metaonly config Types.Common$ common$;

DETAILS

All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.

Instance Creation

index URL

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

create();

// Create an instance-object

ISync.query() // instance

index URL

Query for a particular quality

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

Bool query(Int qual);

ARGUMENTS

qual — quality

RETURNS

TRUE or FALSE.

DETAILS

FALSE is returned if quality not supported.

ISync.signal() // instance

index URL

Called at completion of an activity

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

Void signal();

DETAILS

This function is non-blocking. It is also required that the underlying sync be binary in nature.

This function does not take an Error.Block intentionally because it can be called from ISR context.

ISync.wait() // instance

index URL

Called to wait/poll for completion of an activity

XDCspec declarations sourced in xdc/runtime/knl/ISync.xdc

Int wait(UInt timeout, Error.Block *eb);

ARGUMENTS

timeout — Timeout in microseconds

eb — Hist Pointer to Error.Block

RETURNS

Refer to description above

DETAILS

This function can block. Non-blocking implementations should return WaitStatus_TIMEOUT to indicate a timeout.

WaitStatus_ERROR if an error occured.
WaitStatus_TIMEOUT denotes timeout.
WaitStatus_SUCCESS semaphore was decremented.

generated on Thu, 01 Mar 2012 16:58:44 GMT