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 /*
15 * ======== ISemaphore.xdc ========
16 */
17
18 import xdc.runtime.Error;
19
20 /*!
21 * ======== ISemaphore ========
22 * Interface implemented by all front-end semaphore providers.
23 * {@link #SemThread} and {@link #SemProcess}. [EXPERIMENTAL]
24 *
25 * Semaphores can be used for synchronization and mutual exclusion.
26 *
27 * pend() is used to wait for a semaphore. The timeout parameter allows the
28 * caller to wait until a timeout, wait indefinitely, or not wait at all.
29 * The return value indicates whether or not the wait was successful.
30 *
31 * post() is used to signal a semaphore. If no thread is waiting on the
32 * semaphore, then post() increments the semaphore count (for binary
33 * semaphores, the count is always 0 or 1).
34 *
35 * getCount() returns the count of the semaphore.
36 *
37 * reset() sets the semaphore count to a given value. There should be no
38 * threads waiting on the semaphore when reset() is called.
39 *
40 */
41 interface ISemaphore {
42
43 /*!
44 * ======== PendStatus ========
45 * Error codes returned by Semaphore_pend
46 */
47 enum PendStatus {
48 PendStatus_ERROR = -1,
49 PendStatus_TIMEOUT = 0,
50 PendStatus_SUCCESS = 1
51 };
52 /*! Used as the timeout value to specify wait forever */
53 const UInt FOREVER = ~(0);
54
55 /*! Types of semaphores. */
56 enum Mode {
57 Mode_COUNTING, /*! Counting semaphore. */
58 Mode_BINARY /*! Binary Semaphore. */
59 };
60
61 instance:
62
63 /*!
64 * ======== mode ========
65 * Semaphore mode. Default is COUNTING.
66 *
67 * When mode is BINARY , the semaphore has only two states, available
68 * and unavailable. When mode is COUNTING, the semaphore keeps track of
69 * number of times a semaphore is posted.
70 */
71 config Mode mode = Mode_COUNTING;
72
73 /*!
74 * ======== pend ========
75 * Wait for the semaphore to become available.
76 *
77 * @p(blist) 78 * -{@link #PendStatus_ERROR} if an error occured.
79 * -{@link #PendStatus_TIMEOUT} denotes timeout.
80 * -{@link #PendStatus_SUCCESS} semaphore was decremented.
81 * details.
82 * @p 83 *
84 * @param(timeout) timeout in microseconds
85 * @param(eb) error block
86 * @a(returns) refer to description above
87 */
88 Int pend(UInt timeout, Error.Block *eb);
89
90 /*!
91 * ======== post ========
92 * Increment the semaphore count.
93 *
94 * @param(eb) error block
95 * @a(returns) true for success, false for error in error block
96 */
97 Bool post(Error.Block *eb);
98 }
99
100 /*
101 *! Revision History
102 *! ================
103 *! 17-Apr-2009 nitya Review updates
104 */
105
106 /*
107 * @(#) xdc.runtime.knl; 1, 0, 0,43; 11-25-2009 11:25:45; /db/ztree/library/trees/xdc/xdc-u14x/src/packages/
108 */
109