module xdc.runtime.knl.SyncNull

index URL

Empty ISync implementation used mainly for testing

C synopsis
Individual elements
XDCscript usage
Individual elements

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

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

Functions
Void	SyncNull_construct// Initialize a new instance object inside the provided structure(SyncNull_Struct structP, const SyncNull_Params params);
SyncNull_Handle	SyncNull_create// Allocate and initialize a new instance object and return its handle(const SyncNull_Params params, Error_Block eb);
Void	SyncNull_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SyncNull_Handle *handleP);
Void	SyncNull_destruct// Finalize the instance object inside the provided structure(SyncNull_Struct *structP);
Void	SyncNull_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SyncNull_Params *params);
Functions common to all ISync modules
Bool	SyncNull_query// Query for a particular quality(SyncNull_Handle handle, Int qual);
Void	SyncNull_signal// Called at completion of an activity(SyncNull_Handle handle);
Int	SyncNull_wait// Called to wait/poll for completion of an activity(SyncNull_Handle handle, UInt timeout, Error_Block *eb);
Functions common to all target instances
	SyncNull_handle// Convert this instance structure pointer into an instance handle, SyncNull_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SyncNull_Handle_label// The label associated with this instance object, SyncNull_Handle_name// The name of this instance object, SyncNull_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SyncNull_Object_count// The number of statically-created instance objects, SyncNull_Object_first// The handle of the first dynamically-created instance object, or NULL, SyncNull_Object_get// The handle of the i-th statically-created instance object (array == NULL), SyncNull_Object_heap// The heap used to allocate dynamically-created instance objects, SyncNull_Object_next// The handle of the next dynamically-created instance object, or NULL, SyncNull_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	SyncNull_Module_getMask// Returns the diagnostics mask for this module, SyncNull_Module_hasMask// Test whether this module has a diagnostics mask, SyncNull_Module_heap// The heap from which this module allocates memory, SyncNull_Module_id// Get this module's unique id, SyncNull_Module_setMask// Set the diagnostics mask for this module, SyncNull_Module_startupDone// Test if this module has completed startup
Defines
#define	SyncNull_NO_WAIT// Used to specify no waiting (UInt)0
#define	SyncNull_Q_BLOCKING// Blocking quality (Int)1
#define	SyncNull_WAIT_FOREVER// Used to wait forever (UInt)~(0)
Typedefs
typedef SyncNull_Object *	SyncNull_Handle// Client reference to an instance object;
typedef struct	SyncNull_Object// Opaque internal representation of an instance object SyncNull_Object;
typedef struct	SyncNull_Params// Instance config-params structure ...
typedef struct	SyncNull_Struct// Opaque client structure large enough to hold an instance object SyncNull_Struct;
typedef enum	SyncNull_WaitStatus// Error codes returned by ISync_wait ...

const SyncNull_NO_WAIT

index URL

Used to specify no waiting

C synopsis target-domain

#define SyncNull_NO_WAIT (UInt)0

const SyncNull_Q_BLOCKING

index URL

Blocking quality

C synopsis target-domain

#define SyncNull_Q_BLOCKING (Int)1

DETAILS

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

const SyncNull_WAIT_FOREVER

index URL

Used to wait forever

C synopsis target-domain

#define SyncNull_WAIT_FOREVER (UInt)~(0)

enum SyncNull_WaitStatus

index URL

Error codes returned by ISync_wait

C synopsis target-domain

typedef enum SyncNull_WaitStatus {

SyncNull_WaitStatus_ERROR,

SyncNull_WaitStatus_TIMEOUT,

SyncNull_WaitStatus_SUCCESS

} SyncNull_WaitStatus;

Module-Wide Built-Ins

index URL

C synopsis target-domain

Types_ModuleId SyncNull_Module_id();

// Get this module's unique id

Bool SyncNull_Module_startupDone();

// Test if this module has completed startup

IHeap_Handle SyncNull_Module_heap();

// The heap from which this module allocates memory

Bool SyncNull_Module_hasMask();

// Test whether this module has a diagnostics mask

Bits16 SyncNull_Module_getMask();

// Returns the diagnostics mask for this module

Void SyncNull_Module_setMask(Bits16 mask);

// Set the diagnostics mask for this module

Instance Object Types

index URL

C synopsis target-domain

typedef struct SyncNull_Object SyncNull_Object;

// Opaque internal representation of an instance object

typedef SyncNull_Object *SyncNull_Handle;

// Client reference to an instance object

typedef struct SyncNull_Struct SyncNull_Struct;

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

SyncNull_Handle SyncNull_handle(SyncNull_Struct *structP);

// Convert this instance structure pointer into an instance handle

SyncNull_Struct *SyncNull_struct(SyncNull_Handle handle);

// Convert this instance handle into an instance structure pointer

Instance Config Parameters

index URL

C synopsis target-domain

typedef struct SyncNull_Params {

// Instance config-params structure

IInstance_Params *instance;

// Common per-instance configs

} SyncNull_Params;

Void SyncNull_Params_init(SyncNull_Params *params);

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

Instance Creation

index URL

C synopsis target-domain

SyncNull_Handle SyncNull_create(const SyncNull_Params *params, Error_Block *eb);

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

Void SyncNull_construct(SyncNull_Struct *structP, const SyncNull_Params *params);

// 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 SyncNull_delete(SyncNull_Handle *handleP);

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

Void SyncNull_destruct(SyncNull_Struct *structP);

// Finalize the instance object inside the provided structure

SyncNull_query() // instance

index URL

Query for a particular quality

C synopsis target-domain

Bool SyncNull_query(SyncNull_Handle handle, Int qual);

ARGUMENTS

handle — handle of a previously-created SyncNull instance object

qual — quality

RETURNS

TRUE or FALSE.

DETAILS

FALSE is returned if quality not supported.

SyncNull_signal() // instance

index URL

Called at completion of an activity

C synopsis target-domain

Void SyncNull_signal(SyncNull_Handle handle);

ARGUMENTS

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

SyncNull_wait() // instance

index URL

Called to wait/poll for completion of an activity

C synopsis target-domain

Int SyncNull_wait(SyncNull_Handle handle, UInt timeout, Error_Block *eb);

ARGUMENTS

handle — handle of a previously-created SyncNull 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 SyncNull_Handle_upCast(SyncNull_Handle handle);

// unconditionally move one level up the inheritance hierarchy

SyncNull_Handle SyncNull_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 SyncNull_Object_count();

// The number of statically-created instance objects

SyncNull_Handle SyncNull_Object_get(SyncNull_Object *array, Int i);

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

SyncNull_Handle SyncNull_Object_first();

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

SyncNull_Handle SyncNull_Object_next(SyncNull_Handle handle);

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

IHeap_Handle SyncNull_Object_heap();

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

Types_Label *SyncNull_Handle_label(SyncNull_Handle handle, Types_Label *buf);

// The label associated with this instance object

String SyncNull_Handle_name(SyncNull_Handle handle);

// The name of this instance object

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

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

module-wide constants & types

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

const SyncNull.Q_BLOCKING// Blocking quality = 1;

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

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

const SyncNull.WaitStatus_ERROR;

const SyncNull.WaitStatus_TIMEOUT;

const SyncNull.WaitStatus_SUCCESS;

module-wide config parameters

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

per-instance config parameters

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

per-instance creation

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

const SyncNull.NO_WAIT

index URL

Used to specify no waiting

XDCscript usage meta-domain

const SyncNull.NO_WAIT = 0;

C SYNOPSIS

SyncNull_NO_WAIT

const SyncNull.Q_BLOCKING

index URL

Blocking quality

XDCscript usage meta-domain

const SyncNull.Q_BLOCKING = 1;

DETAILS

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

C SYNOPSIS

SyncNull_Q_BLOCKING

const SyncNull.WAIT_FOREVER

index URL

Used to wait forever

XDCscript usage meta-domain

const SyncNull.WAIT_FOREVER = ~(0);

C SYNOPSIS

SyncNull_WAIT_FOREVER

enum SyncNull.WaitStatus

index URL

Error codes returned by ISync_wait

XDCscript usage meta-domain

values of type SyncNull.WaitStatus

const SyncNull.WaitStatus_ERROR;

const SyncNull.WaitStatus_TIMEOUT;

const SyncNull.WaitStatus_SUCCESS;

C SYNOPSIS

SyncNull_WaitStatus

metaonly config SyncNull.common$ // module-wide

index URL

Common module configuration parameters

XDCscript usage meta-domain

SyncNull.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 SyncNull.Params;

// Instance config-params object

Instance Creation

index URL

XDCscript usage meta-domain

var params = new SyncNull.Params;

// Allocate instance config-params

params.config = ...

// Assign individual configs

var inst = SyncNull.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, 27 Sep 2012 23:21:09 GMT