1 /*****************************************************************************/
2 /* Software Testing Automation Framework (STAF)                              */
3 /* (C) Copyright IBM Corp. 2001                                              */
4 /*                                                                           */
5 /* This software is licensed under the Eclipse Public License (EPL) V1.0.    */
6 /*****************************************************************************/
7 
8 #ifndef STAF_MutexSem
9 #define STAF_MutexSem
10 
11 #include "STAF.h"
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 /* Begin C language definitions */
18 
19 #define STAF_MUTEX_SEM_INDEFINITE_WAIT (unsigned int)-1
20 
21 typedef struct STAFMutexSemImplementation *STAFMutexSem_t;
22 
23 /***********************************************************************/
24 /* STAFMutexSemConstruct - Creates a STAF Mutex sempahore              */
25 /*                                                                     */
26 /* Accepts: (Out) Pointer to a mutex                                   */
27 /*          (In)  The name of the mutex (This should be 0/NULL for a   */
28 /*                private mutex) (Currently only private mutexes are   */
29 /*                supported)                                           */
30 /*          (Out) Pointer to OS return code                            */
31 /*                                                                     */
32 /* Returns:  kSTAFOk, on success                                       */
33 /*           other on error                                            */
34 /***********************************************************************/
35 STAFRC_t STAFMutexSemConstruct(STAFMutexSem_t *pMutex,
36                                const char *name, unsigned int *osRC);
37 
38 /***********************************************************************/
39 /* STAFMutexSemRequest - Requests ownership of a STAF Mutex semaphore  */
40 /*                                                                     */
41 /* Accepts: (In)  Pointer to a mutex                                   */
42 /*          (In)  The amount of time to wait (in milliseconds)         */
43 /*          (Out) Pointer to OS return code                            */
44 /*                                                                     */
45 /* Returns:  kSTAFOk, on success                                       */
46 /*           kSTAFTimeout, on timeout                                  */
47 /*           other on error                                            */
48 /***********************************************************************/
49 STAFRC_t STAFMutexSemRequest(STAFMutexSem_t mutex, unsigned int timeout,
50                              unsigned int *osRC);
51 
52 
53 /***********************************************************************/
54 /* STAFMutexSemRelease - Releases ownership of a STAF Mutex semaphore  */
55 /*                                                                     */
56 /* Accepts: (In)  Pointer to a mutex                                   */
57 /*          (Out) Pointer to OS return code                            */
58 /*                                                                     */
59 /* Returns:  kSTAFOk, on success                                       */
60 /*           other on error                                            */
61 /***********************************************************************/
62 STAFRC_t STAFMutexSemRelease(STAFMutexSem_t mutex, unsigned int *osRC);
63 
64 
65 /***********************************************************************/
66 /* STAFMutexSemDestruct - Destructs a STAF Mutex semaphore             */
67 /*                                                                     */
68 /* Accepts: (In)  Pointer to a mutex                                   */
69 /*          (Out) Pointer to OS return code                            */
70 /*                                                                     */
71 /* Returns:  kSTAFOk, on success                                       */
72 /*           other on error                                            */
73 /***********************************************************************/
74 STAFRC_t STAFMutexSemDestruct(STAFMutexSem_t *pMutex, unsigned int *osRC);
75 
76 /* End C language definitions */
77 
78 #ifdef __cplusplus
79 }
80 
81 // Begin C++ language definitions
82 
83 #include "STAFRefPtr.h"
84 #include "STAFException.h"
85 
86 // Forward declaration for typedef
87 class STAFMutexSem;
88 typedef STAFRefPtr<STAFMutexSem> STAFMutexSemPtr;
89 
90 // STAFMutexSem - This class provides a C++ wrapper around the STAF Mutex
91 //                C APIs.  This class will throw exceptions in all error
92 //                cases except for a timeout on a request().
93 
94 class STAFMutexSem
95 {
96 public:
97 
98     STAFMutexSem();
99 
100     // Returns: kSTAFOk, if the semaphore was acquired
101     //          kSTAFTimeout, if you timed out waiting
102     STAFRC_t request(unsigned int timeout = STAF_MUTEX_SEM_INDEFINITE_WAIT);
103     void release();
104 
105     ~STAFMutexSem();
106 
107 private:
108 
109     // Don't allow copy or assignment
110     STAFMutexSem(const STAFMutexSem &);
111     STAFMutexSem &operator=(const STAFMutexSem &);
112 
113     STAFMutexSem_t fMutexImpl;
114 };
115 
116 
117 // STAFMutexSemLock - This class provides a simply way to acquire a STAFMutexSem
118 //                    for the duration of a block
119 
120 class STAFMutexSemLock
121 {
122 public:
123 
124     STAFMutexSemLock(STAFMutexSem &theMutex,
125                      unsigned int timeout = STAF_MUTEX_SEM_INDEFINITE_WAIT)
fMutex(theMutex)126         : fMutex(theMutex)
127     { fMutex.request(timeout); }
128 
~STAFMutexSemLock()129     ~STAFMutexSemLock()
130     { fMutex.release(); }
131 
132 private:
133 
134     STAFMutexSem &fMutex;
135 };
136 
137 
138 // Now include inline definitions
139 
140 #ifndef STAF_NATIVE_COMPILER
141 #include "STAFMutexSemInlImpl.cpp"
142 #endif
143 
144 // End C++ language definitions
145 
146 // End #ifdef __cplusplus
147 #endif
148 
149 #endif
150 
151 
152