interface xdc.runtime.IGateProvider |
![](../../Arrow_left.png) |
![](../../Arrow_up.png) |
![](../../Arrow_right.png) |
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 ... ]
interface IGateProvider { ...
instance: ...
interface IGateProvider {
module-wide constants & types
module-wide config parameters
module-wide functions
instance:
per-instance creation
per-instance functions
}
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 |
![](../../Arrow_up.png) |
Blocking quality
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 |
![](../../Arrow_up.png) |
Preempting quality
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 |
![](../../Arrow_up.png) |
Common module configuration parameters
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 |
![](../../Arrow_up.png) |
Runtime test for a particular gate quality
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 |
![](../../Arrow_up.png) |
Configuration time test for a particular gate quality
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 |
![](../../Arrow_up.png) |
create();
// Create an instance-object
IGateProvider.enter() // instance |
![](../../Arrow_up.png) |
Enter this gate
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 |
![](../../Arrow_up.png) |
Leave this gate
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, 16 Jun 2011 22:52:51 GMT