summaryrefslogtreecommitdiff
path: root/ACE/ace/Token_Request_Reply.h
blob: d1e88edf5a3165d7a10e20fbd9767f5cb0cafdce (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
// -*- C++ -*-

//=============================================================================
/**
 *  @file    Token_Request_Reply.h
 *
 *   Define the format used to exchange messages between the
 *   ACE_Token Server and its clients.
 *
 *  @author Douglas C. Schmidt (d.schmidt@vanderbilt.edu)
 *  @author Tim Harrison (harrison@cs.wustl.edu)
 */
//=============================================================================


#ifndef ACE_TOKEN_REQUEST_REPLY_H
#define ACE_TOKEN_REQUEST_REPLY_H
#include /**/ "ace/pre.h"

#include "ace/Local_Tokens.h"

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

#if defined (ACE_HAS_TOKENS_LIBRARY)

ACE_BEGIN_VERSIONED_NAMESPACE_DECL

/// Specifies the size of the fixed length portion of
/// the Transfer structure in ACE_Token_Request
#define ACE_TOKEN_REQUEST_HEADER_SIZE 40

/**
 * @class ACE_Token_Request
 *
 * @brief Message format for delivering requests to the ACE_Token Server.
 *
 * This class is implemented to minimize data copying.
 * In particular, all marshaling is done in situ...
 */
class ACE_Export ACE_Token_Request
{
public:
  /// Operation types.
  enum OPERATION
  {
    /// Acquire the token.
    ACQUIRE,
    /// Release the token.
    RELEASE,
    /// Renew the token.
    RENEW,
    /// Remove the token.
    REMOVE,
    // Try to acquire the token.
    TRY_ACQUIRE
  };

  /// Default constructor.
  ACE_Token_Request () = default;

  /**
   * @param token_type MUTEX, RWLOCK
   * @param proxy_type MUTEX, RLOCK, WLOCK (acquires mean different things)
   * @param operation method
   * @param token_name
   * @param client_id
   * @param options We check USE_TIMEOUT and use the arg.
   */
  ACE_Token_Request (int token_type,
                     int proxy_type,
                     ACE_UINT32 operation,
                     const ACE_TCHAR token_name[],
                     const ACE_TCHAR client_id[],
                     const ACE_Synch_Options &options);

  /// Get the length of the encoded/decoded message.
  ACE_UINT32 length () const;

  /// Set the length of the encoded/decoded message.
  void length (ACE_UINT32);

  /// Get the type of proxy
  int proxy_type () const;

  /// Set the type of proxy
  void proxy_type (int proxy_type);

  /// Get the type of token
  int token_type () const;

  /// Set the type of token
  void token_type (int token_type);

  /// Get the type of the operation.
  ACE_UINT32 operation_type () const;

  /// Set the type of the operation.
  void operation_type (ACE_UINT32);

  /// Get the requeue position.  These should be used when renew
  /// is the operation type.
  ACE_UINT32 requeue_position () const;

  /// Set the requeue position.  These should be used when renew
  /// is the operation type.
  void requeue_position (ACE_UINT32);

  /// Get notify.  These should be used when acquire is the operation type.
  ACE_UINT32 notify () const;

  /// Set notify.  These should be used when acquire is the operation type.
  void notify (ACE_UINT32);

  /// Get the timeout.
  ACE_Synch_Options &options () const;

  /// Set the timeout.
  void options (const ACE_Synch_Options &options);

  // = Set/get the name of the token and the client id.  The set
  // method is combined to make it easier on us.  We're copying the
  // names as a contiguous buffer.
  ACE_TCHAR *token_name () const;
  ACE_TCHAR *client_id () const;
  void token_name (const ACE_TCHAR *token_name, const ACE_TCHAR *client_id);

  /// Encode the message before transmission.
  int encode (void *&);

  /// Decode message after reception.  This must be called to set the
  /// internal options.
  int decode ();

  /// Print out the values of the message for debugging purposes.
  void dump () const;

private:
  // = The 5 fields in the <Transfer> struct are transmitted to the server.
  // The remaining 2 fields are not tranferred -- they are used only on
  // the server-side to simplify lookups.

  struct Transfer
  {
    /// Length of entire request.
    ACE_UINT32 length_;

    /// Type of the request (i.e., MUTEX, RLOCK, WLOCK...
    ACE_UINT32 token_type_;

    /// Type of the request (i.e., MUTEX, RLOCK, WLOCK...
    ACE_UINT32 proxy_type_;

    /// Type of the request (i.e., <ACQUIRE>, <RELEASE>, <RENEW>, and <REMOVE>).
    ACE_UINT32 operation_type_;

    /// this only makes sense when operation type is renew
    ACE_UINT32 requeue_position_;

    /// this only makes sense when operation type is renew
    ACE_UINT32 notify_;

    // = ACE_Synch_Options stuff

    /// Indicates if we should block forever.  If 1, then <secTimeout_>
    /// and <usecTimeout_> indicates how long we should wait.  If 0,
    /// then we block forever.
    ACE_UINT32 use_timeout_;

    /// Max seconds willing to wait for token if not blocking forever.
    ACE_UINT32 sec_;

    /// Max micro seconds to wait for token if not blocking forever.
    ACE_UINT32 usec_;

    /// value returned in <Token_Reply::arg>;
    ACE_UINT32 arg_;

    /// The data portion contains the <tokenName_> including a 0 terminator,
    /// a ':', then the <clientId> including a 0 terminator
    ACE_TCHAR data_[ACE_MAXTOKENNAMELEN + ACE_MAXCLIENTIDLEN + 3];
  } transfer_;

  /// Pointer to the beginning of the token name in this->data_.
  ACE_TCHAR *token_name_ {};

  /// Pointer to the beginning of the client id in this->data_;
  ACE_TCHAR *client_id_ {};

  /// Holds arg, sec, usec, etc.
  ACE_Synch_Options options_;
};

/**
 * @class ACE_Token_Reply
 *
 * @brief Message format for delivering replies from the ACE_Token Server.
 *
 * This class is implemented to minimize data copying.
 * In particular, all marshaling is done in situ...
 */
class ACE_Export ACE_Token_Reply
{
public:
  /// Default constructor.
  ACE_Token_Reply ();

  /// Get the length of the encoded/decoded message.
  ACE_UINT32 length () const;

  /// Set the length of the encoded/decoded message.
  void length (ACE_UINT32);

  /// Get the errno of a reply.
  ACE_UINT32 errnum () const;

  /// Set the errno of a reply.
  void errnum (ACE_UINT32);

  /// Get the arg of a reply.
  ACE_UINT32 arg () const;

  /// Set the arg of a reply.
  void arg (ACE_UINT32);

  /// Encode the message before transfer.
  int encode (void *&);

  /// Decode a message after reception.
  int decode ();

  /// Print out the values of the message for debugging purposes.
  void dump () const;

private:
  /// The 2 fields in the <Transfer> struct are transmitted to the server.
  struct Transfer
  {
    /// Length of entire reply.
    ACE_UINT32 length_;

    /// Indicates why error occurred if <this->type_> == <FAILURE>.
    /// Typical reasons include:
    ///   @c EWOULDBLOCK (if client requested a non-blocking check for the token).
    ///   @c ETIME (if the client timed out after waiting for the token).
    ///   <ENOLCK> (if the token lock was removed out from underneath a waiter).
    ///   <EACCES> (attempt to renew a token that isn't owned by the client).
    ACE_UINT32 errno_;

    /// magic cookie
    ACE_UINT32 arg_;
  } transfer_;
};

ACE_END_VERSIONED_NAMESPACE_DECL

#if defined (__ACE_INLINE__)
#include "ace/Token_Request_Reply.inl"
#endif /* __ACE_INLINE__ */

#endif /* ACE_HAS_TOKENS_LIBRARY */

#include /**/ "ace/post.h"
#endif /* ACE_TOKEN_REQUEST_REPLY_H */