module ti.sysbios.syncs.SyncEvent

Implements ISync using events

Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Eventmore ... ]
C synopsis target-domain sourced in ti/sysbios/syncs/SyncEvent.xdc
#include <ti/sysbios/syncs/SyncEvent.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 struct
typedef struct
typedef struct
typedef enum
Constants
extern const Assert_Id 
 
DETAILS
Module that implements xdc.runtime.knl.ISync using ti.sysbios.knl.Event
The implementation of xdc.runtime.knl.ISync.wait is empty and returns FALSE for timeout, since with events the pend call is made outside.
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 SyncEvent requires an Event.Handle. When given a null Event.Handle, SynEvent will assert.
 
const SyncEvent_NO_WAIT

Used to specify no waiting

C synopsis target-domain
#define SyncEvent_NO_WAIT (UInt)0
 
 
const SyncEvent_Q_BLOCKING

Blocking quality

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

Used to wait forever

C synopsis target-domain
#define SyncEvent_WAIT_FOREVER (UInt)~(0)
 
 
enum SyncEvent_WaitStatus

Error codes returned by ISync_wait

C synopsis target-domain
typedef enum SyncEvent_WaitStatus {
    SyncEvent_WaitStatus_ERROR,
    SyncEvent_WaitStatus_TIMEOUT,
    SyncEvent_WaitStatus_SUCCESS
} SyncEvent_WaitStatus;
 
 
config SyncEvent_A_nullHandle  // module-wide

Assert when baseHandle is null

C synopsis target-domain
extern const Assert_Id SyncEvent_A_nullHandle;
 
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId SyncEvent_Module_id();
// Get this module's unique id
 
Bool SyncEvent_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle SyncEvent_Module_heap();
// The heap from which this module allocates memory
 
Bool SyncEvent_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 SyncEvent_Module_getMask();
// Returns the diagnostics mask for this module
 
Void SyncEvent_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types

C synopsis target-domain
typedef struct SyncEvent_Object SyncEvent_Object;
// Opaque internal representation of an instance object
 
typedef SyncEvent_Object *SyncEvent_Handle;
// Client reference to an instance object
 
typedef struct SyncEvent_Struct SyncEvent_Struct;
// Opaque client structure large enough to hold an instance object
 
SyncEvent_Handle SyncEvent_handle(SyncEvent_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
SyncEvent_Struct *SyncEvent_struct(SyncEvent_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct SyncEvent_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    Event_Handle event;
    // Event handle must be provided
    UInt eventId;
    // Event id to be when signal() gets invoked
} SyncEvent_Params;
 
Void SyncEvent_Params_init(SyncEvent_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config SyncEvent_Params.event  // instance

Event handle must be provided

C synopsis target-domain
struct SyncEvent_Params {
      ...
    Event_Handle event;
 
 
config SyncEvent_Params.eventId  // instance

Event id to be when signal() gets invoked

C synopsis target-domain
struct SyncEvent_Params {
      ...
    UInt eventId;
 
Runtime Instance Creation

C synopsis target-domain
SyncEvent_Handle SyncEvent_create(const SyncEvent_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void SyncEvent_construct(SyncEvent_Struct *structP, const SyncEvent_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

C synopsis target-domain
Void SyncEvent_delete(SyncEvent_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void SyncEvent_destruct(SyncEvent_Struct *structP);
// Finalize the instance object inside the provided structure
 
SyncEvent_query()  // instance

Query for a particular quality

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

Called at completion of an activity

C synopsis target-domain
Void SyncEvent_signal(SyncEvent_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created SyncEvent 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.
 
SyncEvent_wait()  // instance

Called to wait/poll for completion of an activity

C synopsis target-domain
Int SyncEvent_wait(SyncEvent_Handle handle, UInt timeout, Error_Block *eb);
 
ARGUMENTS
handle — handle of a previously-created SyncEvent 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 SyncEvent_Handle_upCast(SyncEvent_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
SyncEvent_Handle SyncEvent_Handle_downCast(ISync_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins

C synopsis target-domain
Int SyncEvent_Object_count();
// The number of statically-created instance objects
 
SyncEvent_Handle SyncEvent_Object_get(SyncEvent_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
SyncEvent_Handle SyncEvent_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
SyncEvent_Handle SyncEvent_Object_next(SyncEvent_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle SyncEvent_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *SyncEvent_Handle_label(SyncEvent_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String SyncEvent_Handle_name(SyncEvent_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/syncs/SyncEvent.xdc
var SyncEvent = xdc.useModule('ti.sysbios.syncs.SyncEvent');
module-wide constants & types
 
        const SyncEvent.WaitStatus_ERROR;
        const SyncEvent.WaitStatus_TIMEOUT;
        const SyncEvent.WaitStatus_SUCCESS;
module-wide config parameters
        msg: "A_nullHandle: Null handle passed to create"
    };
 
per-instance config parameters
    var params = new SyncEvent.Params// Instance config-params object;
        params.event// Event handle must be provided = Event.Handle null;
per-instance creation
    var inst = SyncEvent.create// Create an instance-object(params);
 
 
const SyncEvent.NO_WAIT

Used to specify no waiting

Configuration settings
const SyncEvent.NO_WAIT = 0;
 
C SYNOPSIS
 
const SyncEvent.Q_BLOCKING

Blocking quality

Configuration settings
const SyncEvent.Q_BLOCKING = 1;
 
DETAILS
Implementations with this "quality" may cause the calling thread to block;
C SYNOPSIS
 
const SyncEvent.WAIT_FOREVER

Used to wait forever

Configuration settings
const SyncEvent.WAIT_FOREVER = ~(0);
 
C SYNOPSIS
 
enum SyncEvent.WaitStatus

Error codes returned by ISync_wait

Configuration settings
values of type SyncEvent.WaitStatus
    const SyncEvent.WaitStatus_ERROR;
    const SyncEvent.WaitStatus_TIMEOUT;
    const SyncEvent.WaitStatus_SUCCESS;
 
C SYNOPSIS
 
config SyncEvent.A_nullHandle  // module-wide

Assert when baseHandle is null

Configuration settings
SyncEvent.A_nullHandle = Assert.Desc {
    msg: "A_nullHandle: Null handle passed to create"
};
 
C SYNOPSIS
 
metaonly config SyncEvent.common$  // module-wide

Common module configuration parameters

Configuration settings
SyncEvent.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

Configuration settings
var params = new SyncEvent.Params;
// Instance config-params object
    params.event = Event.Handle null;
    // Event handle must be provided
    params.eventId = UInt Event.Id_00;
    // Event id to be when signal() gets invoked
 
config SyncEvent.Params.event  // instance

Event handle must be provided

Configuration settings
var params = new SyncEvent.Params;
  ...
params.event = Event.Handle null;
 
C SYNOPSIS
 
config SyncEvent.Params.eventId  // instance

Event id to be when signal() gets invoked

Configuration settings
var params = new SyncEvent.Params;
  ...
params.eventId = UInt Event.Id_00;
 
C SYNOPSIS
Static Instance Creation

Configuration settings
var params = new SyncEvent.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = SyncEvent.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 Tue, 09 Oct 2018 20:57:39 GMT