module xdc.runtime.knl.SemProcess
index URL

SemProcess Manager

This module manages multi-process semaphores through its proxy ISemProcessSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/knl/SemProcess.xdc
#include <xdc/runtime/knl/SemProcess.h>
Functions
Void
SemProcess_construct// Initialize a new instance object inside the provided structure(SemProcess_Struct *structP, Int count, UInt32 key, const SemProcess_Params *params, Error_Block *eb);
SemProcess_Handle
SemProcess_create// Allocate and initialize a new instance object and return its handle(Int count, UInt32 key, const SemProcess_Params *params, Error_Block *eb);
Void
SemProcess_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(SemProcess_Handle *handleP);
Void
SemProcess_destruct// Finalize the instance object inside the provided structure(SemProcess_Struct *structP);
Void
SemProcess_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(SemProcess_Params *params);
Functions common to all ISemaphore modules
Int 
SemProcess_pend// Wait for the semaphore to become available(SemProcess_Handle handle, UInt timeout, Error_Block *eb);
Bool 
SemProcess_post// Increment the semaphore count(SemProcess_Handle handle, Error_Block *eb);
Functions common to all target instances
SemProcess_handle// Convert this instance structure pointer into an instance handle, SemProcess_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, SemProcess_Handle_label// The label associated with this instance object, SemProcess_Handle_name// The name of this instance object, SemProcess_Handle_upCast// unconditionally move one level up the inheritance hierarchy, SemProcess_Object_count// The number of statically-created instance objects, SemProcess_Object_first// The handle of the first dynamically-created instance object, or NULL, SemProcess_Object_get// The handle of the i-th statically-created instance object (array == NULL), SemProcess_Object_heap// The heap used to allocate dynamically-created instance objects, SemProcess_Object_next// The handle of the next dynamically-created instance object, or NULL, SemProcess_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
SemProcess_Module_getMask// Returns the diagnostics mask for this module, SemProcess_Module_hasMask// Test whether this module has a diagnostics mask, SemProcess_Module_heap// The heap from which this module allocates memory, SemProcess_Module_id// Get this module's unique id, SemProcess_Module_setMask// Set the diagnostics mask for this module, SemProcess_Module_startupDone// Test if this module has completed startup
Defines
#define
SemProcess_FOREVER// Used as the timeout value to specify wait forever (UInt)~(0)
Typedefs
typedef SemProcess_Object *
SemProcess_Handle// Client reference to an instance object;
typedef enum
SemProcess_Mode// Types of semaphores ...
typedef struct
SemProcess_Object// Opaque internal representation of an instance object SemProcess_Object;
typedef struct
SemProcess_Params// Instance config-params structure ...
typedef enum
SemProcess_PendStatus// Error codes returned by Semaphore_pend ...
typedef struct
SemProcess_Struct// Opaque client structure large enough to hold an instance object SemProcess_Struct;
 
DETAILS
This module manages multi-process semaphores through its proxy ISemProcessSupport interface. It has a module wide config parameter Proxy which needs to be bound to an OS specific delegate before this module can be used.
Here is an example showing how the proxy is bound to an BIOS 6.x specific delegate.
  var SemProcess = xdc.useModule('xdc.runtime.knl.SemProcess');
  SemProcess.Proxy = xdc.useModule('ti.sysbios.xdcruntime.SemProcessSupport');
Typically the package containing the delegates have a Settings module that will bind all xdc.runtime.knl proxies. The following example sets up all the xdc.runtime.knl proxies.
  xdc.useModule("ti.sysbios.xdcruntime.Settings");
 
const SemProcess_FOREVER
index URL

Used as the timeout value to specify wait forever

C synopsis target-domain
#define SemProcess_FOREVER (UInt)~(0)
 
 
enum SemProcess_Mode
index URL

Types of semaphores

C synopsis target-domain
typedef enum SemProcess_Mode {
    SemProcess_Mode_COUNTING,
    // Counting semaphore
    SemProcess_Mode_BINARY
    // Binary Semaphore
} SemProcess_Mode;
 
 
enum SemProcess_PendStatus
index URL

Error codes returned by Semaphore_pend

C synopsis target-domain
typedef enum SemProcess_PendStatus {
    SemProcess_PendStatus_ERROR,
    SemProcess_PendStatus_TIMEOUT,
    SemProcess_PendStatus_SUCCESS
} SemProcess_PendStatus;
 
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId SemProcess_Module_id();
// Get this module's unique id
 
Bool SemProcess_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle SemProcess_Module_heap();
// The heap from which this module allocates memory
 
Bool SemProcess_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 SemProcess_Module_getMask();
// Returns the diagnostics mask for this module
 
Void SemProcess_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct SemProcess_Object SemProcess_Object;
// Opaque internal representation of an instance object
 
typedef SemProcess_Object *SemProcess_Handle;
// Client reference to an instance object
 
typedef struct SemProcess_Struct SemProcess_Struct;
// Opaque client structure large enough to hold an instance object
 
SemProcess_Handle SemProcess_handle(SemProcess_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
SemProcess_Struct *SemProcess_struct(SemProcess_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

C synopsis target-domain
typedef struct SemProcess_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
    ISemaphore_Mode mode;
    // Semaphore mode. Default is COUNTING
} SemProcess_Params;
 
Void SemProcess_Params_init(SemProcess_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
 
config SemProcess_mode  // instance
index URL

Semaphore mode. Default is COUNTING

C synopsis target-domain
struct SemProcess_Params {
      ...
    ISemaphore_Mode mode;
 
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
Instance Creation
index URL

C synopsis target-domain
SemProcess_Handle SemProcess_create(Int count, UInt32 key, const SemProcess_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void SemProcess_construct(SemProcess_Struct *structP, Int count, UInt32 key, const SemProcess_Params *params, Error_Block *eb);
// Initialize a new instance object inside the provided structure
ARGUMENTS
count — initial semaphore count
key — globally unique key for SysV-style semaphore
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)
DETAILS
This function creates a new SemProcess object which is initialized to count. All semaphores created with the same key reference the same underlying synchronization object and work between processes.
Instance Deletion
index URL

C synopsis target-domain
Void SemProcess_delete(SemProcess_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void SemProcess_destruct(SemProcess_Struct *structP);
// Finalize the instance object inside the provided structure
 
SemProcess_pend()  // instance
index URL

Wait for the semaphore to become available

C synopsis target-domain
Int SemProcess_pend(SemProcess_Handle handle, UInt timeout, Error_Block *eb);
 
ARGUMENTS
handle — handle of a previously-created SemProcess instance object
timeout — timeout in microseconds
eb — error block
DETAILS
RETURNS
refer to description above
 
SemProcess_post()  // instance
index URL

Increment the semaphore count

C synopsis target-domain
Bool SemProcess_post(SemProcess_Handle handle, Error_Block *eb);
 
ARGUMENTS
handle — handle of a previously-created SemProcess instance object
eb — error block
RETURNS
true for success, false for error in error block
Instance Convertors
index URL

C synopsis target-domain
ISemaphore_Handle SemProcess_Handle_upCast(SemProcess_Handle handle);
// unconditionally move one level up the inheritance hierarchy
 
SemProcess_Handle SemProcess_Handle_downCast(ISemaphore_Handle handle);
// conditionally move one level down the inheritance hierarchy; NULL upon failure
Instance Built-Ins
index URL

C synopsis target-domain
Int SemProcess_Object_count();
// The number of statically-created instance objects
 
SemProcess_Handle SemProcess_Object_get(SemProcess_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
SemProcess_Handle SemProcess_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
SemProcess_Handle SemProcess_Object_next(SemProcess_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle SemProcess_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *SemProcess_Handle_label(SemProcess_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String SemProcess_Handle_name(SemProcess_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in xdc/runtime/knl/SemProcess.xdc
var SemProcess = xdc.useModule('xdc.runtime.knl.SemProcess');
local proxy modules
    SemProcess.Proxy// Proxy that needs to be bound to an OS specific delegate = ISemProcessSupport.Module null
        SemProcess.Proxy.delegate$ = ISemProcessSupport.Module null
        SemProcess.Proxy.abstractInstances$ = false
module-wide constants & types
    const SemProcess.FOREVER// Used as the timeout value to specify wait forever = ~(0);
 
    values of type SemProcess.Mode// Types of semaphores
        const SemProcess.Mode_COUNTING// Counting semaphore;
        const SemProcess.Mode_BINARY// Binary Semaphore;
 
    values of type SemProcess.PendStatus// Error codes returned by Semaphore_pend
        const SemProcess.PendStatus_ERROR;
        const SemProcess.PendStatus_TIMEOUT;
        const SemProcess.PendStatus_SUCCESS;
module-wide config parameters
    SemProcess.common$// Common module configuration parameters = Types.Common$ undefined;
per-instance config parameters
    var params = new SemProcess.Params// Instance config-params object;
        params.mode// Semaphore mode. Default is COUNTING = ISemaphore.Mode ISemaphore.Mode_COUNTING;
per-instance creation
    var inst = SemProcess.create// Create an instance-object(Int count, UInt32 key, params);
 
 
proxy SemProcess.Proxy
index URL

Proxy that needs to be bound to an OS specific delegate

XDCscript usage meta-domain
SemProcess.Proxy = ISemProcessSupport.Module null
// some delegate module inheriting the ISemProcessSupport interface
    SemProcess.Proxy.delegate$ = ISemProcessSupport.Module null
    // explicit access to the currently bound delegate module
    SemProcess.Proxy.abstractInstances$ = false
    // use indirect runtime function calls if true
 
 
const SemProcess.FOREVER
index URL

Used as the timeout value to specify wait forever

XDCscript usage meta-domain
const SemProcess.FOREVER = ~(0);
 
C SYNOPSIS
SemProcess_FOREVER
 
enum SemProcess.Mode
index URL

Types of semaphores

XDCscript usage meta-domain
values of type SemProcess.Mode
    const SemProcess.Mode_COUNTING;
    // Counting semaphore
    const SemProcess.Mode_BINARY;
    // Binary Semaphore
 
C SYNOPSIS
SemProcess_Mode
 
enum SemProcess.PendStatus
index URL

Error codes returned by Semaphore_pend

XDCscript usage meta-domain
values of type SemProcess.PendStatus
    const SemProcess.PendStatus_ERROR;
    const SemProcess.PendStatus_TIMEOUT;
    const SemProcess.PendStatus_SUCCESS;
 
C SYNOPSIS
SemProcess_PendStatus
 
metaonly config SemProcess.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
SemProcess.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 SemProcess.Params;
// Instance config-params object
    params.mode = ISemaphore.Mode ISemaphore.Mode_COUNTING;
    // Semaphore mode. Default is COUNTING
 
config SemProcess.mode  // instance
index URL

Semaphore mode. Default is COUNTING

XDCscript usage meta-domain
var params = new SemProcess.Params;
  ...
params.mode = ISemaphore.Mode ISemaphore.Mode_COUNTING;
 
DETAILS
When mode is BINARY , the semaphore has only two states, available and unavailable. When mode is COUNTING, the semaphore keeps track of number of times a semaphore is posted.
C SYNOPSIS
null
Instance Creation
index URL

XDCscript usage meta-domain
var params = new SemProcess.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = SemProcess.create(Int count, UInt32 key, params);
// Create an instance-object
ARGUMENTS
count — initial semaphore count
key — globally unique key for SysV-style semaphore
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)
DETAILS
This function creates a new SemProcess object which is initialized to count. All semaphores created with the same key reference the same underlying synchronization object and work between processes.
generated on Thu, 27 Sep 2012 23:21:09 GMT