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

//=============================================================================
/**
 *  @file    Activation_Queue.h
 *
 *  $Id$
 *
 *  @author Andres Kruse <Andres.Kruse@cern.ch>
 *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
 */
//=============================================================================

#ifndef ACE_ACTIVATION_QUEUE_H
#define ACE_ACTIVATION_QUEUE_H
#include "ace/pre.h"

#include "ace/Synch_T.h"

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

#include "ace/Message_Queue.h"
#include "ace/Method_Request.h"

// Be compatible with the terminology in the POSA2 book!
#define ACE_Activation_List ACE_Activation_Queue

/**
 * @class ACE_Activation_Queue
 *
 * @brief Reifies a method into a request.  Subclasses typically
 * represent necessary state and behavior.
 *
 * Maintains a priority-ordered queue of ACE_Method_Request objects.
 * A scheduler class (often derived from ACE_Task) subsequently removes
 * each method request and invokes its @c call() method.
 *
 * This class is discussed in depth in the Active Object chapter
 * of POSA2. In that book, it is referred to as an Activation List.
 *
 * @sa ACE_Method_Request
 */
class ACE_Export ACE_Activation_Queue
{
public:
  // = Initialization and termination methods.
  /// Constructor.
  /**
   * Initializes a new activation queue.
   *
   * @param new_queue The activation queue uses an ACE_Message_Queue to
   *                  queue and order the method requests. If this argument
   *                  is 0, a new ACE_Message_Queue is created for this
   *                  object's use and will be deleted when this object is
   *                  destroyed. If a non-zero pointer is supplied, the
   *                  passed object will be used and will not be deleted when
   *                  this object is destroyed. If an ACE_Task is being created
   *                  to act as the scheduler, for instance, its
   *                  ACE_Message_Queue pointer can be passed to this object.
   * @param alloc     Optional, the allocator to use when allocating
   *                  ACE_Message_Block instances that wrap the method requests
   *                  queued to this activation queue. Defaults to
   *                  ACE_Allocator::instance().
   * @param db_alloc  Optional, the allocator to use when allocating
   *                  data blocks for the ACE_Message_Block instances that
   *                  wrap the method requests queued to this activation queue.
   *                  Defaults to ACE_Allocator::instance().
   */
  ACE_Activation_Queue (ACE_Message_Queue<ACE_SYNCH> *new_queue = 0,
                        ACE_Allocator *alloc = 0,
                        ACE_Allocator *db_alloc = 0);

  /// Destructor.
  virtual ~ACE_Activation_Queue (void);

  // = Activate Queue operations.

  /// Dequeue the next available ACE_Method_Request.
  /**
   * @param tv  If 0, the method will block until a method request is
   *            available, else will wait until the absolute time specified
   *            in the referenced ACE_Time_Value.  This method will return,
   *            earlier, however, if queue is closed, deactivated, or when
   *            a signal occurs.
   *
   * @retval    Pointer to the dequeued ACE_Method_Request object.
   * @retval    0 an error occurs; errno contains further information. If
   *            the specified timeout elapses, errno will be @c EWOULDBLOCK.
   */
  ACE_Method_Request *dequeue (ACE_Time_Value *tv = 0);

  /// Enqueue the ACE_Method_Request in priority order.
  /**
   * The priority of the method request is obtained via the @c priority()
   * method of the queued method request. Priority ordering is determined
   * by the ACE_Message_Queue class; 0 is the lowest priority.
   *
   * @param new_method_request  Pointer to the ACE_Method_Request object to
   *            queue. This object's @c priority() method is called to obtain
   *            the priority.
   * @param tv  If 0, the method will block until the method request can
   *            be queued, else will wait until the absolute time specified
   *            in the referenced ACE_Time_Value.  This method will return,
   *            earlier, however, if queue is closed, deactivated, or when
   *            a signal occurs.
   *
   * @retval    0 on success.
   * @retval    -1 if an error occurs; errno contains further information. If
   *            the specified timeout elapses, errno will be @c EWOULDBLOCK.
   */
  int enqueue (ACE_Method_Request *new_method_request,
               ACE_Time_Value *tv = 0);

  /// Get the current number of method objects in the queue.
  size_t method_count (void) const;

  /// Returns 1 if the queue is empty, 0 otherwise.
  int is_empty (void) const;

  /// Returns 1 if the queue is full, 0 otherwise.
  int is_full (void) const;

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

  /// Get a pointer to the underlying queue.
  ACE_Message_Queue<ACE_SYNCH> *queue (void) const;

  /// Set the pointer to the underlying queue.
  void queue (ACE_Message_Queue<ACE_SYNCH> *q);

  /// Declare the dynamic allocation hooks.
  ACE_ALLOC_HOOK_DECLARE;

protected:
  /// Stores the <Method_Requests>.
  ACE_Message_Queue<ACE_SYNCH> *queue_;

  /// Keeps track of whether we need to delete the queue.
  int delete_queue_;

private:
  /// Allocation strategy of the queue.
  ACE_Allocator *allocator_;

  /// Allocation strategy of the message blocks.
  ACE_Allocator *data_block_allocator_;

  // = Prevent assignment and initialization.
  ACE_UNIMPLEMENTED_FUNC (void operator= (const ACE_Activation_Queue &))
  ACE_UNIMPLEMENTED_FUNC (ACE_Activation_Queue (const ACE_Activation_Queue &))
};

#if defined (__ACE_INLINE__)
#include "ace/Activation_Queue.i"
#endif /* __ACE_INLINE__ */

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