interface xdc.runtime.IGateProvider

Interface implemented by all gate providers

Gates are used within the xdc.runtime package to serialize access to data structures that are used by more than one thread. [ more ... ]
XDCspec summary sourced in xdc/runtime/IGateProvider.xdc
interface IGateProvider {  ...
// inherits xdc.runtime.IModule
instance:  ...
XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
package xdc.runtime;
 
interface IGateProvider {
module-wide constants & types
    const Int Q_BLOCKING// Blocking quality = 1;
    const Int Q_PREEMPTING// Preempting quality = 2;
module-wide config parameters
module-wide functions
 
 
 
instance:
per-instance creation
per-instance functions
    IArg enter// Enter this gate();
    Void leave// Leave this gate(IArg key);
}
DETAILS
Gates are used within the xdc.runtime package to serialize access to data structures that are used by more than one thread.
Gates are responsible for ensuring that only one out of multiple threads can access a data structure at a time. There are important scheduling latency and performance considerations that affect the "type" of gate used to protect each data structure. For example, the best way to protect a shared counter is to simply disable all interrupts before the update and restore the interrupt state after the update; disabling all interrupts prevents all thread switching, so the update is guaranteed to be "atomic". Although highly efficient, this method of creating atomic sections causes serious system latencies when the time required to update the data structure can't be bounded.
For example, a memory manager's list of free blocks can grow indefinitely long during periods of high fragmentation. Searching such a list with interrupts disabled would cause system latencies to also become unbounded. In this case, the best solution is to provide a gate that suspends the execution of threads that try to enter a gate that has already been entered; i.e., the gate "blocks" the thread until the thread already in the gate leaves. The time required to enter and leave the gate is greater than simply enabling and restoring interrupts, but since the time spent within the gate is relatively large, the overhead caused by entering and leaving gates will not become a significant percentage of overall system time. More importantly, threads that do not need to access the shared data structure are completely unaffected by threads that do access it.
NOTES
Modules inheriting this interface should treat all names beginning with Q_ as reserved words, i.e. the names from that namespace should not be used. This will allow future version of this interface to define new constants ("qualities") similar to Q_BLOCKING and Q_PREEMPTING without breaking any existing modules.
 
const IGateProvider.Q_BLOCKING

Blocking quality

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
const Int Q_BLOCKING = 1;
 
DETAILS
Gates with this "quality" may cause the calling thread to block; i.e., suspend execution until another thread leaves the gate.
 
const IGateProvider.Q_PREEMPTING

Preempting quality

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
const Int Q_PREEMPTING = 2;
 
DETAILS
Gates with this "quality" allow other threads to preempt the thread that has already entered the gate.
 
metaonly config IGateProvider.common$  // module-wide

Common module configuration parameters

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
metaonly config Types.Common$ common$;
 
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.
 
IGateProvider.query()  // module-wide

Runtime test for a particular gate quality

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
Bool query(Int qual);
 
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
 
metaonly IGateProvider.queryMeta()  // module-wide

Configuration time test for a particular gate quality

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
metaonly Bool queryMeta(Int qual);
 
ARGUMENTS
qual — constant describing a quality
RETURNS
Returns TRUE if the gate has the given quality, and FALSE otherwise, which includes the case when the gate does not recognize the constant describing the quality.
Instance Creation

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
create();
// Create an instance-object
 
IGateProvider.enter()  // instance

Enter this gate

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
IArg enter();
 
DETAILS
Each gate provider can implement mutual exclusion using different algorithms; e.g., disabling all scheduling, disabling the scheduling of all threads below a specified "priority level", suspending the caller when the gate has been entered by another thread and re-enabling it when the the other thread leaves the gate. However, in all cases, after this method returns that caller has exclusive access to the data protected by this gate.
A thread may reenter a gate without blocking or failing.
RETURNS
Returns a "key" that is used to leave this gate; this value is used to restore thread preemption to the state that existed just prior to entering this gate.
 
IGateProvider.leave()  // instance

Leave this gate

XDCspec declarations sourced in xdc/runtime/IGateProvider.xdc
Void leave(IArg key);
 
ARGUMENTS
key — the value returned by a matching call to enter
DETAILS
This method is only called by threads that have previously entered this gate via enter. After this method returns, the caller must not access the data structure protected by this gate (unless the caller has entered the gate more than once and other calls to leave remain to balance the number of previous calls to enter).
generated on Thu, 27 Sep 2012 23:21:04 GMT