← Back to branch summary

~ps10gel/ubuntu/xenial/trafficserver/6.2.0

« back to all changes in this revision

Viewing changes to iocore/eventsystem/I_Action.h

  • Committer: Bazaar Package Importer
  • Author(s): Arno Toell
  • Date: 2011-01-13 11:49:18 UTC
  • Revision ID: james.westby@ubuntu.com-20110113114918-vu422h8dknrgkj15
Tags: upstream-2.1.5-unstable
Import upstream version 2.1.5-unstable

Show diffs side-by-side

added added

removed removed

Lines of Context:
iocore/eventsystem/I_Action.h
 
1
/** @file
 
2
 
 
3
  Generic interface which enables any event or async activity to be cancelled
 
4
 
 
5
  @section license License
 
6
 
 
7
  Licensed to the Apache Software Foundation (ASF) under one
 
8
  or more contributor license agreements.  See the NOTICE file
 
9
  distributed with this work for additional information
 
10
  regarding copyright ownership.  The ASF licenses this file
 
11
  to you under the Apache License, Version 2.0 (the
 
12
  "License"); you may not use this file except in compliance
 
13
  with the License.  You may obtain a copy of the License at
 
14
 
 
15
      http://www.apache.org/licenses/LICENSE-2.0
 
16
 
 
17
  Unless required by applicable law or agreed to in writing, software
 
18
  distributed under the License is distributed on an "AS IS" BASIS,
 
19
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 
20
  See the License for the specific language governing permissions and
 
21
  limitations under the License.
 
22
 
 
23
 */
 
24
 
 
25
#ifndef _I_Action_h_
 
26
#define _I_Action_h_
 
27
 
 
28
#include "libts.h"
 
29
#include "I_Thread.h"
 
30
#include "I_Continuation.h"
 
31
 
 
32
/**
 
33
  Represents an operation initiated on a Processor.
 
34
 
 
35
  The Action class is an abstract representation of an operation
 
36
  being executed by some Processor. A reference to an Action object
 
37
  allows you to cancel an ongoing asynchronous operation before it
 
38
  completes. This means that the Continuation specified for the
 
39
  operation will not be called back.
 
40
 
 
41
  Actions or classes derived from Action are the typical return
 
42
  type of methods exposed by Processors in the Event System and
 
43
  throughout the IO Core libraries.
 
44
 
 
45
  The canceller of an action must be the state machine that will
 
46
  be called back by the task and that state machine's lock must be
 
47
  held while calling cancel.
 
48
 
 
49
  Processor implementers:
 
50
 
 
51
  You must ensure that no events are sent to the state machine after
 
52
  the operation has been cancelled appropriately.
 
53
 
 
54
  Returning an Action:
 
55
 
 
56
  Processor functions that are asynchronous must return actions to
 
57
  allow the calling state machine to cancel the task before completion.
 
58
  Because some processor functions are reentrant, they can call
 
59
  back the state machine before the returning from the call that
 
60
  creates the actions. To handle this case, special values are
 
61
  returned in place of an action to indicate to the state machine
 
62
  that the action is already completed.
 
63
 
 
64
    - @b ACTION_RESULT_DONE The processor has completed the task
 
65
      and called the state machine back inline.
 
66
    - @b ACTION_RESULT_INLINE Not currently used.
 
67
    - @b ACTION_RESULT_IO_ERROR Not currently used.
 
68
 
 
69
  To make matters more complicated, it's possible if the result is
 
70
  ACTION_RESULT_DONE that state machine deallocated itself on the
 
71
  reentrant callback. Thus, state machine implementers MUST either
 
72
  use a scheme to never deallocate their machines on reentrant
 
73
  callbacks OR immediately check the returned action when creating
 
74
  an asynchronous task and if it is ACTION_RESULT_DONE neither read
 
75
  nor write any state variables. With either method, it's imperative
 
76
  that the returned action always be checked for special values and
 
77
  the value handled accordingly.
 
78
 
 
79
  Allocation policy:
 
80
 
 
81
  Actions are allocated by the Processor performing the actions.
 
82
  It is the processor's responsbility to handle deallocation once
 
83
  the action is complete or cancelled. A state machine MUST NOT
 
84
  access an action once the operation that returned the Action has
 
85
  completed or it has cancelled the Action.
 
86
 
 
87
*/
 
88
class Action
 
89
{
 
90
 
 
91
public:
 
92
 
 
93
  /**
 
94
    Contination that initiated this action.
 
95
 
 
96
    The reference to the initiating continuation is only used to
 
97
    verify that the action is being cancelled by the correct
 
98
    continuation.  This field should not be accesed or modified
 
99
    directly by the state machine.
 
100
 
 
101
  */
 
102
  Continuation * continuation;
 
103
 
 
104
 
 
105
  /**
 
106
    Reference to the Continuation's lock.
 
107
 
 
108
    Keeps a reference to the Continuation's lock to preserve the
 
109
    access to the cancelled field valid even when the state machine
 
110
    has been deallocated. This field should not be accesed or
 
111
    modified directly by the state machine.
 
112
 
 
113
  */
 
114
  Ptr<ProxyMutex> mutex;
 
115
 
 
116
  /**
 
117
    Internal flag used to indicate whether the action has been
 
118
    cancelled.
 
119
 
 
120
    This flag is set after a call to cancel or cancel_action and
 
121
    it should not be accesed or modified directly by the state
 
122
    machine.
 
123
 
 
124
  */
 
125
  volatile int cancelled;
 
126
 
 
127
  /**
 
128
    Cancels the asynchronous operation represented by this action.
 
129
 
 
130
    This method is called by state machines willing to cancel an
 
131
    ongoing asynchronous operation. Classes derived from Action may
 
132
    perform additional steps before flagging this action as cancelled.
 
133
    There are certain rules that must be followed in order to cancel
 
134
    an action (see the Remarks section).
 
135
 
 
136
    @param c Continuation associated with this Action.
 
137
 
 
138
  */
 
139
  virtual void cancel(Continuation * c = NULL) {
 
140
    ink_assert(!c || c == continuation);
 
141
#ifdef DEBUG
 
142
    ink_assert(!cancelled);
 
143
    cancelled = true;
 
144
#else
 
145
    if (!cancelled)
 
146
      cancelled = true;
 
147
#endif
 
148
  }
 
149
 
 
150
  /**
 
151
    Cancels the asynchronous operation represented by this action.
 
152
 
 
153
    This method is called by state machines willing to cancel an
 
154
    ongoing asynchronous operation. There are certain rules that
 
155
    must be followed in order to cancel an action (see the Remarks
 
156
    section).
 
157
 
 
158
    @param c Continuation associated with this Action.
 
159
 
 
160
  */
 
161
  void cancel_action(Continuation * c = NULL) {
 
162
    ink_assert(!c || c == continuation);
 
163
#ifdef DEBUG
 
164
    ink_assert(!cancelled);
 
165
    cancelled = true;
 
166
#else
 
167
    if (!cancelled)
 
168
      cancelled = true;
 
169
#endif
 
170
  }
 
171
 
 
172
  Continuation *operator =(Continuation * acont)
 
173
  {
 
174
    continuation = acont;
 
175
    if (acont)
 
176
      mutex = acont->mutex;
 
177
    else
 
178
      mutex = 0;
 
179
    return acont;
 
180
  }
 
181
 
 
182
  /**
 
183
    Constructor of the Action object. Processor implementers are
 
184
    responsible for associating this action with the proper
 
185
    Continuation.
 
186
 
 
187
  */
 
188
Action():continuation(NULL), cancelled(false) {
 
189
  }
 
190
 
 
191
#if defined(__GNUC__)
 
192
  virtual ~ Action() {
 
193
  }
 
194
#endif
 
195
};
 
196
 
 
197
#define ACTION_RESULT_NONE           MAKE_ACTION_RESULT(0)
 
198
#define ACTION_RESULT_DONE           MAKE_ACTION_RESULT(1)
 
199
#define ACTION_IO_ERROR              MAKE_ACTION_RESULT(2)
 
200
#define ACTION_RESULT_INLINE         MAKE_ACTION_RESULT(3)
 
201
 
 
202
// Use these classes by
 
203
// #define ACTION_RESULT_HOST_DB_OFFLINE
 
204
//   MAKE_ACTION_RESULT(ACTION_RESULT_HOST_DB_BASE + 0)
 
205
 
 
206
#define MAKE_ACTION_RESULT(_x) (Action*)(((uintptr_t)((_x<<1)+1)))
 
207
 
 
208
#define ACTION_RESULT(_x) \
 
209
  (int)((((uintptr_t)_x)&1)!=0?(((uintptr_t)>>1):(uintptr_t)0))
 
210
 
 
211
#define IS_ACTION_RESULT(_x) ((((uintptr_t)_x)&1) != 0)
 
212
 
 
213
#endif /*_Action_h_*/