1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 #ifndef __FRAMEWORK_THREADHELP_RESETABLEGUARD_HXX_
25 #define __FRAMEWORK_THREADHELP_RESETABLEGUARD_HXX_
26 
27 //_________________________________________________________________________________________________________________
28 //	my own includes
29 //_________________________________________________________________________________________________________________
30 
31 #include <threadhelp/inoncopyable.h>
32 #include <framework/imutex.hxx>
33 
34 //#ifndef __FRAMEWORK_THREADHELP_THREADHELPBASE_HXX_
35 //#include <threadhelp/threadhelpbase.hxx>
36 //#endif
37 
38 //_________________________________________________________________________________________________________________
39 //	interface includes
40 //_________________________________________________________________________________________________________________
41 
42 //_________________________________________________________________________________________________________________
43 //	other includes
44 //_________________________________________________________________________________________________________________
45 #include <sal/types.h>
46 
47 //_________________________________________________________________________________________________________________
48 //	namespace
49 //_________________________________________________________________________________________________________________
50 
51 namespace framework{
52 
53 //_________________________________________________________________________________________________________________
54 //	const
55 //_________________________________________________________________________________________________________________
56 
57 //_________________________________________________________________________________________________________________
58 //	declarations
59 //_________________________________________________________________________________________________________________
60 
61 /*-************************************************************************************************************//**
62 	@short          implement a guard for implementing save thread access
63 	@descr			These guard has an additional feature to well known one ::osl::Guard.
64 					You can lock() and unlock() it very often!
65 					A set bool flag inside protect this implementation against multiple lock() calls
66 					without any unlock()! So the increasing of guarded mutex couldn't be greater then 1 ...
67 
68     @attention      a) To prevent us against wrong using, the default ctor, copy ctor and the =operator are marked private!
69                     b) Use interface "IMutex" of set LockHelper only - because we must support an exclusiv locking.
70                        Interface "IRWLock" should be used by special guard implementations ... like "ReadGuard" or "WriteGuard"!
71 
72 	@implements		-
73     @base           INonCopyable
74 
75 	@devstatus		ready to use
76 *//*-*************************************************************************************************************/
77 class ResetableGuard : private INonCopyable
78 {
79 	//-------------------------------------------------------------------------------------------------------------
80 	//	public methods
81 	//-------------------------------------------------------------------------------------------------------------
82 	public:
83 
84 		/*-****************************************************************************************************//**
85 			@short		ctors
86 			@descr		Use these ctor methods to initialize the guard right.
87                         Given lock reference must be valid - otherwise crashes could occur!
88 
89 			@seealso	-
90 
91             @param      "pLock", pointer to lock helper of user
92             @param      "rLock", reference to lock helper of user
93 			@return		-
94 
95 			@onerror	-
96 		*//*-*****************************************************************************************************/
ResetableGuard(IMutex * pLock)97         inline ResetableGuard( IMutex* pLock )
98             :   m_pLock    ( pLock     )
99             ,   m_bLocked  ( sal_False )
100         {
101             lock();
102         }
103 
104         //*********************************************************************************************************
ResetableGuard(IMutex & rLock)105         inline ResetableGuard( IMutex& rLock )
106             :   m_pLock    ( &rLock    )
107             ,   m_bLocked  ( sal_False )
108         {
109             lock();
110         }
111 
112 		/*-****************************************************************************************************//**
113 			@short		dtor
114 			@descr		We must release set mutex if programmer forget it ...
115 
116 			@seealso	-
117 
118 			@param		-
119 			@return		-
120 
121 			@onerror	-
122 		*//*-*****************************************************************************************************/
~ResetableGuard()123         inline ~ResetableGuard()
124         {
125             unlock();
126         }
127 
128 		/*-****************************************************************************************************//**
129 			@short		enable/disable the lock
130 			@descr		Use this methods to lock or unlock the mutex.
131 						You can do it so often you wish to do that ...
132 
133             @attention  We use another member to prevent us against multiple acquire calls of the same guard
134                         without suitable release calls!
135                         You don't must protect access at these bool member by using an own mutex ....
136                         because nobody use the same guard instance from different threads!
137                         It will be a function-local object every time.
138 
139 			@seealso	-
140 
141 			@param		-
142 			@return		-
143 
144 			@onerror	-
145 		*//*-*****************************************************************************************************/
lock()146         inline void lock()
147         {
148             if( m_bLocked == sal_False )
149             {
150                 m_pLock->acquire();
151                 m_bLocked = sal_True;
152             }
153         }
154 
155         //*********************************************************************************************************
unlock()156         inline void unlock()
157         {
158             if( m_bLocked == sal_True )
159             {
160                 m_pLock->release();
161                 m_bLocked = sal_False;
162             }
163         }
164 
165 	//-------------------------------------------------------------------------------------------------------------
166 	//	private methods
167 	//-------------------------------------------------------------------------------------------------------------
168 	private:
169 
170 		/*-****************************************************************************************************//**
171 			@short		disable using of these functions!
172 			@descr		It's not allowed to use this methods. Different problems can occur otherwise.
173 						That's why we disable it by making it private.
174 
175 			@seealso	other ctor
176 
177 			@param		-
178 			@return		-
179 
180 			@onerror	-
181 		*//*-*****************************************************************************************************/
182 		ResetableGuard();
183 
184 	//-------------------------------------------------------------------------------------------------------------
185 	//	private member
186 	//-------------------------------------------------------------------------------------------------------------
187 	private:
188 
189         IMutex*         m_pLock     ;   /// pointer to safed lock member of user
190 		sal_Bool		m_bLocked	;	/// protection against multiple lock() calls without unlock()
191 
192 };		//	class ResetableGuard
193 
194 }		//	namespace framework
195 
196 #endif	//	#ifndef __FRAMEWORK_THREADHELP_RESETABLEGUARD_HXX_
197