0030569: Foundation Classes - NCollection_Shared lacks inclusion of NCollection_Defin...
[occt.git] / src / Standard / Standard_Mutex.hxx
CommitLineData
b311480e 1// Created on: 2005-04-10
2// Created by: Andrey BETENEV
973c2be1 3// Copyright (c) 2005-2014 OPEN CASCADE SAS
b311480e 4//
973c2be1 5// This file is part of Open CASCADE Technology software library.
b311480e 6//
d5f74e42 7// This library is free software; you can redistribute it and/or modify it under
8// the terms of the GNU Lesser General Public License version 2.1 as published
973c2be1 9// by the Free Software Foundation, with special exception defined in the file
10// OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11// distribution for complete text of the license and disclaimer of any warranty.
b311480e 12//
973c2be1 13// Alternatively, this file may be used under the terms of Open CASCADE
14// commercial license or contractual agreement.
7fd59977 15
16#ifndef _Standard_Mutex_HeaderFile
17#define _Standard_Mutex_HeaderFile
18
19#include <Standard_Integer.hxx>
20#include <Standard_Boolean.hxx>
536a3cb8 21#include <Standard_ErrorHandler.hxx>
7fd59977 22
d8d01f6e 23#if defined(_WIN32)
49f38e37 24 #include <windows.h>
7fd59977 25#else
49f38e37 26 #include <pthread.h>
d8d01f6e 27 ///#include <sys/errno.h>
49f38e37 28 #include <unistd.h>
29 #include <time.h>
7fd59977 30#endif
31
32/**
33 * @brief Mutex: a class to synchronize access to shared data.
34 *
35 * This is simple encapsulation of tools provided by the
36 * operating system to syncronize access to shared data
37 * from threads within one process.
38 *
39 * Current implementation is very simple and straightforward;
40 * it is just a wrapper around POSIX pthread librray on UNIX/Linux,
41 * and CRITICAL_SECTIONs on Windows NT. It does not provide any
42 * advanced functionaly such as recursive calls to the same mutex from
43 * within one thread (such call will froze the execution).
44 *
45 * Note that all the methods of that class are made inline, in order
46 * to keep maximal performance. This means that a library using the mutex
47 * might need to be linked to threads library directly.
48 *
49 * The typical use of this class should be as follows:
50 * - create instance of the class Standard_Mutex in the global scope
51 * (whenever possible, or as a field of your class)
52 * - create instance of class Standard_Mutex::Sentry using that Mutex
53 * when entering critical section
54 *
55 * Note that this class provides one feature specific to Open CASCADE:
56 * safe unlocking the mutex when signal is raised and converted to OCC
57 * exceptions (Note that with current implementation of this functionality
58 * on UNIX and Linux, C longjumps are used for that, thus destructors of
59 * classes are not called automatically).
60 *
61 * To use this feature, call RegisterCallback() after Lock() or successful
62 * TryLock(), and UnregisterCallback() before Unlock() (or use Sentry classes).
63 */
64
536a3cb8 65class Standard_Mutex : public Standard_ErrorHandler::Callback
7fd59977 66{
67public:
68 /**
69 * @brief Simple sentry class providing convenient interface to mutex.
70 *
71 * Provides automatic locking and unlocking a mutex in its constructor
72 * and destructor, thus ensuring correct unlock of the mutex even in case of
73 * raising an exception or signal from the protected code.
74 *
75 * Create instance of that class when entering critical section.
76 */
77 class Sentry
78 {
79 public:
80
81 //! Constructor - initializes the sentry object by reference to a
82 //! mutex (which must be initialized) and locks the mutex immediately
49f38e37 83 Sentry (Standard_Mutex& theMutex)
84 : myMutex (&theMutex)
7fd59977 85 {
49f38e37 86 Lock();
7fd59977 87 }
88
49f38e37 89 //! Constructor - initializes the sentry object by pointer to a
90 //! mutex and locks the mutex if its pointer is not NULL
91 Sentry (Standard_Mutex* theMutex)
92 : myMutex (theMutex)
93 {
94 if (myMutex != NULL)
95 {
96 Lock();
97 }
98 }
7fd59977 99 //! Destructor - unlocks the mutex if already locked.
49f38e37 100 ~Sentry()
101 {
102 if (myMutex != NULL)
103 {
104 Unlock();
105 }
7fd59977 106 }
107
7fd59977 108 private:
7fd59977 109
7fd59977 110 //! Lock the mutex
49f38e37 111 void Lock()
112 {
113 myMutex->Lock();
114 myMutex->RegisterCallback();
7fd59977 115 }
49f38e37 116
7fd59977 117 //! Unlock the mutex
49f38e37 118 void Unlock()
119 {
120 myMutex->UnregisterCallback();
121 myMutex->Unlock();
7fd59977 122 }
49f38e37 123
7fd59977 124 //! This method should not be called (prohibited).
49f38e37 125 Sentry (const Sentry &);
7fd59977 126 //! This method should not be called (prohibited).
49f38e37 127 Sentry& operator = (const Sentry &);
7fd59977 128
129 private:
49f38e37 130 Standard_Mutex* myMutex;
7fd59977 131 };
49f38e37 132
7fd59977 133public:
134
135 //! Constructor: creates a mutex object and initializes it.
136 //! It is strongly recommended that mutexes were created as
137 //! static objects whenever possible.
138 Standard_EXPORT Standard_Mutex ();
139
140 //! Destructor: destroys the mutex object
141 Standard_EXPORT ~Standard_Mutex ();
142
143 //! Method to lock the mutex; waits until the mutex is released
144 //! by other threads, locks it and then returns
145 Standard_EXPORT void Lock ();
146
147 //! Method to test the mutex; if the mutex is not hold by other thread,
148 //! locks it and returns True; otherwise returns False without waiting
149 //! mutex to be released.
150 Standard_EXPORT Standard_Boolean TryLock ();
151
152 //! Method to unlock the mutex; releases it to other users
be5c3602 153 void Unlock ();
7fd59977 154
155private:
156
157 //! Callback method to unlock the mutex if OCC exception or signal is raised
d65f9183 158 Standard_EXPORT virtual void DestroyCallback() Standard_OVERRIDE;
7fd59977 159
d00cba63 160 //! This method should not be called (prohibited).
161 Standard_Mutex (const Standard_Mutex &);
162 //! This method should not be called (prohibited).
163 Standard_Mutex& operator = (const Standard_Mutex &);
164
7fd59977 165private:
49f38e37 166#if (defined(_WIN32) || defined(__WIN32__))
7fd59977 167 CRITICAL_SECTION myMutex;
168#else
169 pthread_mutex_t myMutex;
170#endif
171};
172
173// Implementation of the method Unlock is inline, since it is
174// just a shortcut to system function
175inline void Standard_Mutex::Unlock ()
176{
49f38e37 177#if (defined(_WIN32) || defined(__WIN32__))
178 LeaveCriticalSection (&myMutex);
7fd59977 179#else
49f38e37 180 pthread_mutex_unlock (&myMutex);
7fd59977 181#endif
182}
183
184#endif /* _Standard_Mutex_HeaderFile */