module xdc.runtime.knl.SyncSemThread

index URL

A ISync implementation based on a SemThread. [EXPERIMENTAL]

C synopsis
Individual elements
XDCscript usage
Individual elements

This module implements the ti.sdo.utils.ISync interface using the xdc.runtime.knl.SemThread module.

C synopsis target-domain sourced in xdc/runtime/knl/SyncSemThread.xdc

#include <xdc/runtime/knl/SyncSemThread.h>

Functions
Void	SyncSemThread_construct// Initialize a new instance object inside the provided structure(SyncSemThread_Struct structP, const SyncSemThread_Params params, Error_Block *eb);
SyncSemThread_Handle	SyncSemThread_create// Allocate and initialize a new instance object and return its handle(const SyncSemThread_Params params, Error_Block eb);
Void	SyncSemThread_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncSemThread_Handle *handleP);
Void	SyncSemThread_destruct// Finalize the instance object inside the provided structure(SyncSemThread_Struct *structP);
Void	SyncSemThread_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncSemThread_Params *params);
Functions common to all ISync modules
Bool	SyncSemThread_query// Query for a particular quality(SyncSemThread_Handle handle, Int qual);
Void	SyncSemThread_signal// Called at completion of an activity(SyncSemThread_Handle handle);
Int	SyncSemThread_wait// Called to wait/poll for completion of an activity(SyncSemThread_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
	SyncSemThread_handle// Convert this instance structure pointer into an instance handle, SyncSemThread_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncSemThread_Handle_label// The label associated with this instance object, SyncSemThread_Handle_name// The name of this instance object, SyncSemThread_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncSemThread_Object_count// The number of statically-created instance objects, SyncSemThread_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncSemThread_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncSemThread_Object_heap// The heap used to allocate dynamically-created instance objects, SyncSemThread_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncSemThread_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	SyncSemThread_Module_getMask// Returns the diagnostics mask for this module, SyncSemThread_Module_hasMask// Test whether this module has a diagnostics mask, SyncSemThread_Module_heap// The heap from which this module allocates memory, SyncSemThread_Module_id// Get this module's unique id, SyncSemThread_Module_setMask// Set the diagnostics mask for this module, SyncSemThread_Module_startupDone// Test if this module has completed startup
Defines
#define	SyncSemThread_NO_WAIT// Used to specify no waiting (UInt)0
#define	SyncSemThread_Q_BLOCKING// Blocking quality (Int)1
#define	SyncSemThread_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncSemThread_Object *	SyncSemThread_Handle// Client reference to an instance object;
typedef struct	SyncSemThread_Object// Opaque internal representation of an instance object SyncSemThread_Object;
typedef struct	SyncSemThread_Params// Instance config-params structure ...
typedef struct	SyncSemThread_Struct// Opaque client structure large enough to hold an instance object SyncSemThread_Struct;
typedef enum	SyncSemThread_WaitStatus// Error codes returned by ISync_wait ...

const SyncSemThread_NO_WAIT

index URL

Used to specify no waiting

C synopsis target-domain

#define SyncSemThread_NO_WAIT (UInt)0

const SyncSemThread_Q_BLOCKING

index URL

Blocking quality

C synopsis target-domain

#define SyncSemThread_Q_BLOCKING (Int)1

DETAILS

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

const SyncSemThread_WAIT_FOREVER

index URL

Used to wait forever

C synopsis target-domain

#define SyncSemThread_WAIT_FOREVER (UInt)~(0)

enum SyncSemThread_WaitStatus

index URL

Error codes returned by ISync_wait

C synopsis target-domain

typedef enum SyncSemThread_WaitStatus {

SyncSemThread_WaitStatus_ERROR,

SyncSemThread_WaitStatus_TIMEOUT,

SyncSemThread_WaitStatus_SUCCESS

} SyncSemThread_WaitStatus;

Module-Wide Built-Ins

index URL

C synopsis target-domain

Types_ModuleId SyncSemThread_Module_id();

// Get this module's unique id

Bool SyncSemThread_Module_startupDone();

// Test if this module has completed startup

IHeap_Handle SyncSemThread_Module_heap();

// The heap from which this module allocates memory

Bool SyncSemThread_Module_hasMask();

// Test whether this module has a diagnostics mask

Bits16 SyncSemThread_Module_getMask();

// Returns the diagnostics mask for this module

Void SyncSemThread_Module_setMask(Bits16 mask);

// Set the diagnostics mask for this module

Instance Object Types

index URL

C synopsis target-domain

typedef struct SyncSemThread_Object SyncSemThread_Object;

// Opaque internal representation of an instance object

typedef SyncSemThread_Object *SyncSemThread_Handle;

// Client reference to an instance object

typedef struct SyncSemThread_Struct SyncSemThread_Struct;

// Opaque client structure large enough to hold an instance object

SyncSemThread_Handle SyncSemThread_handle(SyncSemThread_Struct *structP);

// Convert this instance structure pointer into an instance handle

SyncSemThread_Struct *SyncSemThread_struct(SyncSemThread_Handle handle);

// Convert this instance handle into an instance structure pointer

Instance Config Parameters

index URL

C synopsis target-domain

typedef struct SyncSemThread_Params {

// Instance config-params structure

IInstance_Params *instance;

// Common per-instance configs

} SyncSemThread_Params;

Void SyncSemThread_Params_init(SyncSemThread_Params *params);

// Initialize this config-params structure with supplier-specified defaults before instance creation

Instance Creation

index URL

C synopsis target-domain

SyncSemThread_Handle SyncSemThread_create(const SyncSemThread_Params *params, Error_Block *eb);

// Allocate and initialize a new instance object and return its handle

Void SyncSemThread_construct(SyncSemThread_Struct *structP, const SyncSemThread_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

index URL

C synopsis target-domain

Void SyncSemThread_delete(SyncSemThread_Handle *handleP);

// Finalize and free this previously allocated instance object, setting the referenced handle to NULL

Void SyncSemThread_destruct(SyncSemThread_Struct *structP);

// Finalize the instance object inside the provided structure

SyncSemThread_query() // instance

index URL

Query for a particular quality

C synopsis target-domain

Bool SyncSemThread_query(SyncSemThread_Handle handle, Int qual);

ARGUMENTS

handle — handle of a previously-created SyncSemThread instance object

qual — quality

RETURNS

TRUE or FALSE.

DETAILS

FALSE is returned if quality not supported.

SyncSemThread_signal() // instance

index URL

Called at completion of an activity

C synopsis target-domain

Void SyncSemThread_signal(SyncSemThread_Handle handle);

ARGUMENTS

handle — handle of a previously-created SyncSemThread 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.

SyncSemThread_wait() // instance

index URL

Called to wait/poll for completion of an activity

C synopsis target-domain

Int SyncSemThread_wait(SyncSemThread_Handle handle, UInt timeout, Error_Block *eb);

ARGUMENTS

handle — handle of a previously-created SyncSemThread 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.

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

Instance Convertors

index URL

C synopsis target-domain

ISync_Handle SyncSemThread_Handle_upCast(SyncSemThread_Handle handle);

// unconditionally move one level up the inheritance hierarchy

SyncSemThread_Handle SyncSemThread_Handle_downCast(ISync_Handle handle);

// conditionally move one level down the inheritance hierarchy; NULL upon failure

Instance Built-Ins

index URL

C synopsis target-domain

Int SyncSemThread_Object_count();

// The number of statically-created instance objects

SyncSemThread_Handle SyncSemThread_Object_get(SyncSemThread_Object *array, Int i);

// The handle of the i-th statically-created instance object (array == NULL)

SyncSemThread_Handle SyncSemThread_Object_first();

// The handle of the first dynamically-created instance object, or NULL

SyncSemThread_Handle SyncSemThread_Object_next(SyncSemThread_Handle handle);

// The handle of the next dynamically-created instance object, or NULL

IHeap_Handle SyncSemThread_Object_heap();

// The heap used to allocate dynamically-created instance objects

Types_Label *SyncSemThread_Handle_label(SyncSemThread_Handle handle, Types_Label *buf);

// The label associated with this instance object

String SyncSemThread_Handle_name(SyncSemThread_Handle handle);

// The name of this instance object

XDCscript usage meta-domain sourced in xdc/runtime/knl/SyncSemThread.xdc

var SyncSemThread = xdc.useModule('xdc.runtime.knl.SyncSemThread');

module-wide constants & types

const SyncSemThread.NO_WAIT// Used to specify no waiting = 0;

const SyncSemThread.Q_BLOCKING// Blocking quality = 1;

const SyncSemThread.WAIT_FOREVER// Used to wait forever = ~(0);

values of type SyncSemThread.WaitStatus// Error codes returned by ISync_wait

const SyncSemThread.WaitStatus_ERROR;

const SyncSemThread.WaitStatus_TIMEOUT;

const SyncSemThread.WaitStatus_SUCCESS;

module-wide config parameters

SyncSemThread.common$// Common module configuration parameters = Types.Common$ undefined;

per-instance config parameters

var params = new SyncSemThread.Params// Instance config-params object;

per-instance creation

var inst = SyncSemThread.create// Create an instance-object(params);

const SyncSemThread.NO_WAIT

index URL

Used to specify no waiting

XDCscript usage meta-domain

const SyncSemThread.NO_WAIT = 0;

C SYNOPSIS

SyncSemThread_NO_WAIT

const SyncSemThread.Q_BLOCKING

index URL

Blocking quality

XDCscript usage meta-domain

const SyncSemThread.Q_BLOCKING = 1;

DETAILS

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

C SYNOPSIS

SyncSemThread_Q_BLOCKING

const SyncSemThread.WAIT_FOREVER

index URL

Used to wait forever

XDCscript usage meta-domain

const SyncSemThread.WAIT_FOREVER = ~(0);

C SYNOPSIS

SyncSemThread_WAIT_FOREVER

enum SyncSemThread.WaitStatus

index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain

values of type SyncSemThread.WaitStatus

const SyncSemThread.WaitStatus_ERROR;

const SyncSemThread.WaitStatus_TIMEOUT;

const SyncSemThread.WaitStatus_SUCCESS;

C SYNOPSIS

SyncSemThread_WaitStatus

metaonly config SyncSemThread.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

SyncSemThread.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

index URL

XDCscript usage meta-domain

var params = new SyncSemThread.Params;

// Instance config-params object

Instance Creation

index URL

XDCscript usage meta-domain

var params = new SyncSemThread.Params;

// Allocate instance config-params

params.config = ...

// Assign individual configs

var inst = SyncSemThread.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:46 GMT