1 /* --COPYRIGHT--,ESD
2 * Copyright (c) 2008 Texas Instruments. All rights reserved.
3 * This program and the accompanying materials are made available under the
4 * terms of the Eclipse Public License v1.0 and Eclipse Distribution License
5 * v. 1.0 which accompanies this distribution. The Eclipse Public License is
6 * available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
7 * Distribution License is available at
8 * http://www.eclipse.org/org/documents/edl-v10.php.
9 *
10 * Contributors:
11 * Texas Instruments - initial implementation
12 * --/COPYRIGHT--*/
13 /*
14 * ======== IGateProvider.xdc ========
15 *
16 *! Revision History
17 *! ================
18 *! 10-Mar-2008 sasha reviewed and made some changes in cdoc
19 */
20 package xdc.runtime
21
22 /*!
23 * ======== IGateProvider ========
24 * Interface implemented by all gate providers
25 *
26 * Gates are used within the `xdc.runtime` package to serialize access
27 * to data structures that are used by more than one thread.
28 *
29 * Gates are responsible for ensuring that only one out of multiple threads
30 * can access a data structure at a time. There
31 * are important scheduling latency and performance considerations that
32 * affect the "type" of gate used to protect each data structure. For
33 * example, the best way to protect a shared counter is to simply disable
34 * all interrupts before the update and restore the interrupt state after
35 * the update; disabling all interrupts prevents all thread switching, so
36 * the update is guaranteed to be "atomic". Although highly efficient, this
37 * method of creating atomic sections causes serious system latencies when
38 * the time required to update the data structure can't be bounded.
39 *
40 * For example, a memory manager's list of free blocks can grow indefinitely
41 * long during periods of high fragmentation. Searching such a list with
42 * interrupts disabled would cause system latencies to also become unbounded.
43 * In this case, the best solution is to provide a gate that suspends the
44 * execution of threads that try to enter a gate that has already been
45 * entered; i.e., the gate "blocks" the thread until the thread
46 * already in the gate leaves. The time required to enter and leave the
47 * gate is greater than simply enabling and restoring interrupts, but since
48 * the time spent within the gate is relatively large, the overhead caused by
49 * entering and leaving gates will not become a significant percentage of
50 * overall system time. More importantly, threads that do not need to
51 * access the shared data structure are completely unaffected by threads
52 * that do access it.
53 *
54 * @a(Notes) 55 * Modules inheriting this interface should treat all names beginning with
56 * `Q_` as reserved words, i.e. the names from that namespace should not
57 * be used. This will allow future version of this interface to define new
58 * constants ("qualities" ) similar to `{@link #Q_BLOCKING}` and
59 * `{@link #Q_PREEMPTING}` without breaking any existing modules.
60 */
61 interface IGateProvider {
62
63 /*!
64 * ======== Q_BLOCKING ========
65 * Blocking quality
66 *
67 * Gates with this "quality" may cause the calling thread to block;
68 * i.e., suspend execution until another thread leaves the gate.
69 */
70 const Int Q_BLOCKING = 1;
71
72 /*!
73 * ======== Q_PREEMPTING ========
74 * Preempting quality
75 *
76 * Gates with this "quality" allow other threads to preempt the thread
77 * that has already entered the gate.
78 */
79 const Int Q_PREEMPTING = 2;
80
81 /*!
82 * ======== query ========
83 * Configuration time test for a particular gate quality
84 *
85 * @param(qual) constant describing a quality
86 * @a(returns) Returns `TRUE` if the gate has the given quality,
87 * and `FALSE` otherwise, which includes the case when the gate does not
88 * recognize the constant describing the quality.
89 */
90 metaonly Bool queryMeta(Int qual);
91
92 /*!
93 * ======== query ========
94 * Runtime test for a particular gate quality
95 *
96 * @param(qual) constant describing a quality
97 * @a(returns) Returns `TRUE` if the gate has the given quality,
98 * and `FALSE` otherwise, which includes the case when the gate does not
99 * recognize the constant describing the quality.
100 */
101 Bool query(Int qual);
102
103 instance:
104
105 /*!
106 * ======== create ========
107 * Create a gate instance
108 */
109 create();
110
111 /*!
112 * ======== enter ========
113 * Enter this gate
114 *
115 * Each gate provider can implement mutual exclusion using different
116 * algorithms; e.g., disabling all scheduling, disabling the scheduling
117 * of all threads below a specified "priority level", suspending the
118 * caller when the gate has been entered by another thread and
119 * re-enabling it when the the other thread leaves the gate. However,
120 * in all cases, after this method returns that caller has exclusive
121 * access to the data protected by this gate.
122 *
123 * A thread may reenter a gate without blocking or failing.
124 *
125 * @a(returns) 126 * Returns a "key" that is used to `{@link #leave}` this gate; this
127 * value is used to restore thread preemption to the state that
128 * existed just prior to entering this gate.
129 */
130 IArg enter();
131
132 /*!
133 * ======== leave ========
134 * Leave this gate
135 *
136 * This method is only called by threads that have previously entered
137 * this gate via `{@link #enter}`. After this method returns, the
138 * caller must not access the data structure protected by this gate
139 * (unless the caller has entered the gate more than once and other
140 * calls to `leave` remain to balance the number of previous
141 * calls to `enter`).
142 *
143 * @param(key) the value returned by a matching call to
144 * `{@link #enter}`
145 */
146 Void leave(IArg key);
147 }
148 /*
149 * @(#) xdc.runtime; 2, 0, 0, 0,214; 7-29-2009 14:53:43; /db/ztree/library/trees/xdc-t56x/src/packages/
150 */
151