module ti.sysbios.syncs.SyncSem

Implements ISyncs using semaphores

Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Semaphoremore ... ]
C synopsis target-domain sourced in ti/sysbios/syncs/SyncSem.xdc
#include <ti/sysbios/syncs/SyncSem.h>
Functions
Void
Void
Void
Void
Functions common to all ISync modules
Bool 
Void 
Int 
Functions common to all target instances
Functions common to all target modules
Defines
#define
#define
#define
Typedefs
typedef SyncSem_Object *
typedef struct
typedef struct
typedef struct
typedef enum
 
DETAILS
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Semaphore
Modules like ti.sdo.io.Stream use an ISync.Handle for selecting the synchronization mechanism. This allows Stream to be independent of the synchronization mechanism.
An instance of SyncSem requires a Semaphore.Handle. When given a null Semaphore.Handle, SynSem will create a Semaphore for its use. Note that the underlying Semaphore has to be binary in nature and initialized as being unavailable.
 
const SyncSem_NO_WAIT

Used to specify no waiting

C synopsis target-domain
#define SyncSem_NO_WAIT (UInt)0
 
 
const SyncSem_Q_BLOCKING

Blocking quality

C synopsis target-domain
#define SyncSem_Q_BLOCKING (Int)1
 
DETAILS
Implementations with this "quality" may cause the calling thread to block;
 
const SyncSem_WAIT_FOREVER

Used to wait forever

C synopsis target-domain
#define SyncSem_WAIT_FOREVER (UInt)~(0)
 
 
enum SyncSem_WaitStatus

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncSem_WaitStatus {
    SyncSem_WaitStatus_ERROR,
    SyncSem_WaitStatus_TIMEOUT,
    SyncSem_WaitStatus_SUCCESS
} SyncSem_WaitStatus;
 
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId SyncSem_Module_id();
// Get this module's unique id
 
Bool SyncSem_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle SyncSem_Module_heap();
// The heap from which this module allocates memory
 
Bool SyncSem_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 SyncSem_Module_getMask();
// Returns the diagnostics mask for this module
 
Void SyncSem_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct SyncSem_Object SyncSem_Object;
// Opaque internal representation of an instance object
 
typedef SyncSem_Object *SyncSem_Handle;
// Client reference to an instance object
 
typedef struct SyncSem_Struct SyncSem_Struct;
// Opaque client structure large enough to hold an instance object
 
SyncSem_Handle SyncSem_handle(SyncSem_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
SyncSem_Struct *SyncSem_struct(SyncSem_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct SyncSem_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    Semaphore_Handle sem;
    // Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance
} SyncSem_Params;
 
Void SyncSem_Params_init(SyncSem_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config SyncSem_sem  // instance

Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance

C synopsis target-domain
struct SyncSem_Params {
      ...
    Semaphore_Handle sem;
 
Instance Creation

C synopsis target-domain
SyncSem_Handle SyncSem_create(const SyncSem_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void SyncSem_construct(SyncSem_Struct *structP, const SyncSem_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion

C synopsis target-domain
Void SyncSem_delete(SyncSem_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void SyncSem_destruct(SyncSem_Struct *structP);
// Finalize the instance object inside the provided structure
 
SyncSem_query()  // instance

Query for a particular quality

C synopsis target-domain
Bool SyncSem_query(SyncSem_Handle handle, Int qual);
 
ARGUMENTS
handle — handle of a previously-created SyncSem instance object
qual — quality
RETURNS
TRUE or FALSE.
DETAILS
FALSE is returned if quality not supported.
 
SyncSem_signal()  // instance

Called at completion of an activity

C synopsis target-domain
Void SyncSem_signal(SyncSem_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created SyncSem instance object
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.
 
SyncSem_wait()  // instance

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncSem_wait(SyncSem_Handle handle, UInt timeout, Error_Block *eb);
 
ARGUMENTS
handle — handle of a previously-created SyncSem instance object
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.
Instance Convertors

C synopsis target-domain
ISync_Handle SyncSem_Handle_upCast(SyncSem_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
SyncSem_Handle SyncSem_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int SyncSem_Object_count();
// The number of statically-created instance objects
 
SyncSem_Handle SyncSem_Object_get(SyncSem_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
SyncSem_Handle SyncSem_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
SyncSem_Handle SyncSem_Object_next(SyncSem_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle SyncSem_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *SyncSem_Handle_label(SyncSem_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String SyncSem_Handle_name(SyncSem_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sysbios/syncs/SyncSem.xdc
var SyncSem = xdc.useModule('ti.sysbios.syncs.SyncSem');
module-wide constants & types
 
        const SyncSem.WaitStatus_ERROR;
        const SyncSem.WaitStatus_TIMEOUT;
        const SyncSem.WaitStatus_SUCCESS;
module-wide config parameters
per-instance config parameters
    var params = new SyncSem.Params// Instance config-params object;
per-instance creation
    var inst = SyncSem.create// Create an instance-object(params);
 
 
const SyncSem.NO_WAIT

Used to specify no waiting

XDCscript usage meta-domain
const SyncSem.NO_WAIT = 0;
 
C SYNOPSIS
 
const SyncSem.Q_BLOCKING

Blocking quality

XDCscript usage meta-domain
const SyncSem.Q_BLOCKING = 1;
 
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
 
const SyncSem.WAIT_FOREVER

Used to wait forever

XDCscript usage meta-domain
const SyncSem.WAIT_FOREVER = ~(0);
 
C SYNOPSIS
 
enum SyncSem.WaitStatus

Error codes returned by ISync_wait

XDCscript usage meta-domain
values of type SyncSem.WaitStatus
    const SyncSem.WaitStatus_ERROR;
    const SyncSem.WaitStatus_TIMEOUT;
    const SyncSem.WaitStatus_SUCCESS;
 
C SYNOPSIS
 
metaonly config SyncSem.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
SyncSem.common$ = Types.Common$ undefined;
 
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 Config Parameters

XDCscript usage meta-domain
var params = new SyncSem.Params;
// Instance config-params object
    params.sem = Semaphore.Handle null;
    // Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance
 
config SyncSem.sem  // instance

Semaphore handle to be used. When Semaphore.Handle is null SyncSem will create a Semaphore instance

XDCscript usage meta-domain
var params = new SyncSem.Params;
  ...
params.sem = Semaphore.Handle null;
 
C SYNOPSIS
Instance Creation

XDCscript usage meta-domain
var params = new SyncSem.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = SyncSem.create(params);
// Create an instance-object
ARGUMENTS
params — per-instance config params, or NULL to select default values (target-domain only)
eb — active error-handling block, or NULL to select default policy (target-domain only)
generated on Thu, 01 Mar 2012 16:58:15 GMT