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