summaryrefslogtreecommitdiff
path: root/ace/Token.h
blob: 009cf53f1a7025ad9fbf2a6b76b205270497ecff (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
/* -*- C++ -*- */
// $Id$

// ============================================================================
//
// = LIBRARY
//    ace
//
// = FILENAME
//    Token.h
//
// = AUTHOR
//    Original author -- Karl-Heinz Dorn (kdorn@erlh.siemens.de)
//    Ported to ACE by Douglas C. Schmidt (schmidt@cs.wustl.edu)
//
// ============================================================================

#ifndef ACE_TOKEN_H
#define ACE_TOKEN_H

#include "ace/Synch.h"

#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

#if defined (ACE_HAS_THREADS)

#if (defined (ACE_WIN32) && !defined (ACE_HAS_WINCE)) || defined (VXWORKS) || defined (ACE_PSOS)
// If platforms support semaphores with timed wait, then we use semaphores instead of c.v.
# define ACE_TOKEN_USES_SEMAPHORE
#endif /* (ACE_WIN32 && !ACE_HAS_WINCE) || VXWORKS || ACE_PSOS */

class ACE_Export ACE_Token
{
  // = TITLE
  //    Class that acquires, renews, and releases a synchronization
  //    token that is serviced in strict FIFO ordering and that also
  //    supports readers/writer semantics.
  //
  // = DESCRIPTION
  //    This class is a more general-purpose synchronization mechanism
  //    than SunOS 5.x mutexes.  For example, it implements "recursive
  //    mutex" semantics, where a thread that owns the token can
  //    reacquire it without deadlocking.  In addition, threads that
  //    are blocked awaiting the token are serviced in strict FIFO
  //    order as other threads release the token (Solaris and Pthread
  //    mutexes don't strictly enforce an acquisition order).  There
  //    are two FIFO lists within the class.  Write acquires always
  //    have higher priority over read acquires.  Which means, if you
  //    use both write/read operations, care must be taken to avoid
  //    starvation on the readers.  Notice that the read/write acquire
  //    operations do not have the usual semantic of reader/writer
  //    locks.  Only one reader can acquire the token at a time (which
  //    is different from the usual reader/writer locks where several
  //    readers can acquire a lock at the same time as long as there
  //    is no writer waiting for the lock.)  We choose the names 1.)
  //    to borrow the semantic to give writers higher priority, and,
  //    2.) to support a common interface over all locking classes in
  //    ACE.
public:
  // = Initialization and termination.

  ACE_Token (LPCTSTR name = 0, void * = 0);
  virtual ~ACE_Token (void);

  // = Synchronization operations.

  int acquire (void (*sleep_hook)(void *),
               void *arg = 0,
               ACE_Time_Value *timeout = 0);
  // Acquire the token, sleeping until it is obtained or until the
  // expiration of <timeout>, which is treated as "absolute" time.  If
  // some other thread currently holds the token then <sleep_hook> is
  // called before our thread goes to sleep.  This <sleep_hook> can be
  // used by the requesting thread to unblock a token-holder that is
  // sleeping, e.g., by means of writing to a pipe (the ACE
  // ACE_Reactor uses this functionality).  Return values: 0 if
  // acquires without calling <sleep_hook> 1 if <sleep_hook> is
  // called.  2 if the token is signaled.  -1 if failure or timeout
  // occurs (if timeout occurs errno == ETIME) If <timeout> ==
  // <&ACE_Time_Value::zero> then acquire has polling semantics (and
  // does *not* call <sleep_hook>).

  int acquire (ACE_Time_Value *timeout = 0);
  // This behaves just like the previous <acquire> method, except
  // that it invokes the virtual function called <sleep_hook>
  // that can be overridden by a subclass of ACE_Token.

  virtual void sleep_hook (void);
  // This should be overridden by a subclass to define
  // the appropriate behavior before <acquire> goes to sleep.
  // By default, this is a no-op...

  int renew (int requeue_position = 0,
             ACE_Time_Value *timeout = 0);
  // An optimized method that efficiently reacquires the token if no
  // other threads are waiting.  This is useful for situations where
  // you don't want to degrad the quality of service if there are
  // other threads waiting to get the token.  If <requeue_position> ==
  // -1 and there are other threads waiting to obtain the token we are
  // queued at the end of the list of waiters.  If <requeue_position>
  // > -1 then it indicates how many entries to skip over before
  // inserting our thread into the list of waiters (e.g.,
  // <requeue_position> == 0 means "insert at front of the queue").
  // Renew has the rather odd semantics such that if there are other
  // waiting threads it will give up the token even if the
  // nesting_level_ > 1.  I'm not sure if this is really the right
  // thing to do (since it makes it possible for shared data to be
  // changed unexpectedly) so use with caution...
  // This method maintians the original token priority.
  // As in <acquire>, the <timeout> value is an absolute time.

  int tryacquire (void);
  // Become interface-compliant with other lock mechanisms (implements
  // a non-blocking <acquire>).

  int remove (void);
  // Shuts down the ACE_Token instance.

  int release (void);
  // Relinquish the token.  If there are any waiters then the next one
  // in line gets it.

  int acquire_read (void);
  // Behave like acquire but in a lower priority.  It should probably
  // be called acquire_yield.

  int acquire_read (void (*sleep_hook)(void *),
               void *arg = 0,
               ACE_Time_Value *timeout = 0);
  // More sophisticate version of acquire_read.

  int acquire_write (void);
  // Just calls <acquire>.

  int acquire_write (void (*sleep_hook)(void *),
               void *arg = 0,
               ACE_Time_Value *timeout = 0);
  // More sophisticate version of acquire_write.

  int tryacquire_read (void);
  // Lower priority try_acquire.

  int tryacquire_write (void);
  // Just calls <tryacquire>.

  // = Accessor methods.

  int waiters (void);
  // Return the number of threads that are currently waiting to get
  // the token.

  ACE_thread_t current_owner (void);
  // Return the id of the current thread that owns the token.

  int signal_all_threads (void);
  // Force all threads waiting to acquire the token to return one by
  // one.  The method sets the <signal_all_thread_> to non-zero if
  // there're threads waiting, and returns the number of threads
  // waiting.  If there's no thread waiting for the token, the call
  // returns 0 and doesn't do anything.  The last thread releases the
  // token also reset the <singal_all_thread_> flag to 0.  This means,
  // any threads that try to acquire the token after the call is
  // issued will also get "signaled" and the number of threads waiting
  // the token is only a snapshot.

  void dump (void) const;
  // Dump the state of an object.

  ACE_ALLOC_HOOK_DECLARE;
  // Declare the dynamic allocation hooks.

  // = The following structure implements a ACE_FIFO of waiter threads
  // that are asleep waiting to obtain the token.

  struct ACE_Token_Queue_Entry
  {
    ACE_Token_Queue_Entry (ACE_Thread_Mutex &m,
                           ACE_thread_t t_id);
    // Constructor

    ACE_Token_Queue_Entry (ACE_Thread_Mutex &m,
                           ACE_thread_t t_id,
                           ACE_Condition_Attributes &attributes);
    // Constructor using a pre-allocated attributes

    int wait (ACE_Time_Value *timeout, ACE_Thread_Mutex &lock);
    // Entry blocks on the token.

    int signal (void);
    // Notify (unblock) the entry.

    ACE_Token_Queue_Entry *next_;
    // Pointer to next waiter.

    ACE_thread_t thread_id_;
    // ACE_Thread id of this waiter.

#if defined (ACE_TOKEN_USES_SEMAPHORE)
    ACE_Semaphore cv_;
    // ACE_Semaphore object used to wake up waiter when it can run again.
#else
    ACE_Condition_Thread_Mutex cv_;
    // ACE_Condition object used to wake up waiter when it can run again.
#endif /* ACE_TOKEN_USES_SEMAPHORE */

    int runable_;
    // Ok to run.
  };

private:
  enum ACE_Token_Op_Type
  {
    READ_TOKEN = 1,
    WRITE_TOKEN
  };

  struct ACE_Token_Queue
  {
    ACE_Token_Queue (void);

    void remove_entry (ACE_Token_Queue_Entry *);
    // Remove a waiter from the queue (used when a timeout occurs).

    ACE_Token_Queue_Entry *head_;
    // Head of the list of waiting threads.

    ACE_Token_Queue_Entry *tail_;
    // Tail of the list of waiting threads.
  };

  int shared_acquire (void (*sleep_hook_func)(void *),
                      void *arg,
                      ACE_Time_Value *timeout,
                      ACE_Token_Op_Type op_type);
  // Implements the <acquire> and <tryacquire> methods above.

  ACE_Token_Queue writers_;
  // A queue of writer threads.

  ACE_Token_Queue readers_;
  // A queue of reader threads.

  ACE_Thread_Mutex lock_;
  // ACE_Thread_Mutex used to lock internal data structures.

  ACE_thread_t owner_;
  // Current owner of the token.

  int in_use_;
  // Some thread (i.e., <owner_>) is using the token.  We need this
  // extra variable to deal with POSIX pthreads madness...

  int waiters_;
  // Number of waiters.

  int nesting_level_;
  // Current nesting level.

  int signal_all_threads_;
  // Whether we are "signaling" all threads or not.

  ACE_Condition_Attributes attributes_;
  // The attributes for the condition variables, optimizes lock time.
};

#if defined (__ACE_INLINE__)
#include "ace/Synch_T.h"
#include "ace/Token.i"
#endif /* __ACE_INLINE__ */
#else
class ACE_Export ACE_Token
{
public:
  int acquire (ACE_Time_Value * = 0) { ACE_NOTSUP_RETURN (-1); }
  int tryacquire (void) { ACE_NOTSUP_RETURN (-1); }
  int remove (void) { ACE_NOTSUP_RETURN (-1); }
  int release (void) { ACE_NOTSUP_RETURN (-1); }
};
#endif /* ACE_HAS_THREADS */
#endif /* ACE_TOKEN_H */