ACE/ace/Module.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Module.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_MODULE_H
  12 #define ACE_MODULE_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Task_T.h"
  23 #include "ace/os_include/os_dirent.h"
  24
  25 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  26
  27 /**
  28  * @class ACE_Module_Base
  29  *
  30  * @brief Workaround HP/C++ compiler bug with enums in templates.
  31  *
  32  * Certain C++ compilers, e.g., the HP/UX 10.x and 9.x compilers,
  33  * seem to fail if enums are defined inside a template, hence we
  34  * have to move them into a base class.
  35  */
  36 class ACE_Export ACE_Module_Base
  37 {
  38 public:
  39   enum
  40   {
  41     /// Indicates that the flags have not been set
  42     M_FLAGS_NOT_SET = 0,
  43
  44     /// Indicates that close() should delete the writer Task.
  45     M_DELETE_READER = 1,
  46
  47     /// Indicates that close() should delete the reader Task.
  48     M_DELETE_WRITER = 2,
  49
  50     /// Indicates that close() deletes the Tasks.
  51     /**
  52      * Don't change this value without updating the same enum in class
  53      * ACE_Stream...
  54      * The M_DELETE_READER and M_DELETE_WRITER flags may be or'ed
  55      * together.
  56      */
  57     M_DELETE = 3,
  58
  59     /// Indicates that close() should not delete any Tasks.
  60     M_DELETE_NONE = 4
  61   };
  62
  63   virtual ~ACE_Module_Base () = default;
  64 };
  65
  66 /**
  67  * @class ACE_Module
  68  *
  69  * @brief An abstraction for managing a bi-directional flow of messages.
  70  *
  71  * This is based on the Module concept in System V Streams,
  72  * which contains a pair of Tasks, one for handling upstream
  73  * processing, one for handling downstream processing.  In
  74  * general, you shouldn't subclass from this class, but instead
  75  * subclass from the ACE_Task.
  76  */
  77 template <ACE_SYNCH_DECL, class TIME_POLICY = ACE_System_Time_Policy>
  78 class ACE_Module : public ACE_Module_Base
  79 {
  80 public:
  81   /// Create an empty Module.
  82   ACE_Module ();
  83
  84   /// Shutdown the Module.
  85   virtual ~ACE_Module ();
  86
  87   /// Create an initialized module with @a module_name as its identity
  88   /// and @a reader and @a writer as its tasks.
  89   ACE_Module (const ACE_TCHAR *module_name,
  90               ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *writer = 0,
  91               ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *reader = 0,
  92               void *args = 0,
  93               int flags = M_DELETE);
  94
  95   /**
  96    * Initialize the module with @a module_name as its identity
  97    * and @a reader> and @a writer as its tasks.  Previously register
  98    * reader or writers or closed down and deleted according to the
  99    * value of flags_.  Should not be called from within
 100    * <ACE_Task::module_closed>.
 101    */
 102   int open (const ACE_TCHAR *module_name,
 103             ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *writer = 0,
 104             ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *reader = 0,
 105             void *a = 0,
 106             int flags = M_DELETE);
 107
 108   /**
 109    * Close down the module and its tasks.  The flags argument can be
 110    * used to override the default behaviour, which depends on previous
 111    * @a flags values in calls to c'tor, <open>, <reader>, and <writer>.
 112    * A previous value M_DELETE[_XXX] can not be overridden.  Should
 113    * not be called from within <ACE_Task::module_closed>.
 114    */
 115   int close (int flags = M_DELETE_NONE);
 116
 117   // = ACE_Task manipulation routines
 118   /// Get the writer task.
 119   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *writer ();
 120
 121   /**
 122    * Set the writer task. @a flags can be used to indicate that the
 123    * module should delete the writer during a call to close or to the
 124    * destructor. If a previous writer exists, it is closed.  It may
 125    * also be deleted, depending on the old flags_ value.  Should not
 126    * be called from within <ACE_Task::module_closed>.
 127    */
 128   void writer (ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *q, int flags = M_DELETE_WRITER);
 129
 130   /// Get the reader task.
 131   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *reader ();
 132
 133   /**
 134    * Set the reader task. @a flags can be used to indicate that the
 135    * module should delete the reader during a call to close or to the
 136    * destructor. If a previous reader exists, it is closed.  It may
 137    * also be deleted, depending on the old flags_ value.  Should not
 138    * be called from within <ACE_Task::module_closed>.
 139    */
 140   void reader (ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *q, int flags = M_DELETE_READER);
 141
 142   /// Set and get pointer to sibling ACE_Task in an ACE_Module
 143   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *sibling (ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *orig);
 144
 145   // = Identify the module
 146   /// Get the module name.
 147   const ACE_TCHAR *name () const;
 148
 149   /// Set the module name.
 150   void name (const ACE_TCHAR *);
 151
 152   // = Argument to the Tasks.
 153   /// Get the argument passed to the tasks.
 154   void *arg () const;
 155
 156   /// Set the argument passed to the tasks.
 157   void arg (void *);
 158
 159   /// Link to other modules in the ustream stack
 160   void link (ACE_Module<ACE_SYNCH_USE, TIME_POLICY> *m);
 161
 162   /// Get the next pointer to the module above in the stream.
 163   virtual ACE_Module<ACE_SYNCH_USE, TIME_POLICY> *next ();
 164
 165   /// Set the next pointer to the module above in the stream.
 166   virtual void next (ACE_Module<ACE_SYNCH_USE, TIME_POLICY> *m);
 167
 168   /// Dump the state of an object.
 169   void dump () const;
 170
 171   /// Declare the dynamic allocation hooks.
 172   ACE_ALLOC_HOOK_DECLARE;
 173
 174 private:
 175   /// Implements the close operation for either the reader or the
 176   /// writer task (depending on @a which).
 177   int close_i (int which, int flags);
 178
 179   /// Pair of Tasks that form the "read-side" and "write-side" of the
 180   /// ACE_Module partitioning.
 181   ACE_Task<ACE_SYNCH_USE, TIME_POLICY> *q_pair_[2];
 182
 183   /// Name of the ACE_Module.
 184   ACE_TCHAR name_[MAXPATHLEN + 1];
 185
 186   /// Next ACE_Module in the stack.
 187   ACE_Module<ACE_SYNCH_USE, TIME_POLICY> *next_;
 188
 189   /// Argument passed through to the reader and writer task when they
 190   /// are opened.
 191   void *arg_;
 192
 193   /// Holds flags which are used to determine if the reader and writer
 194   /// task have to be deleted on exit
 195   int flags_;
 196 };
 197
 198 ACE_END_VERSIONED_NAMESPACE_DECL
 199
 200 #if defined (__ACE_INLINE__)
 201 #include "ace/Module.inl"
 202 #endif /* __ACE_INLINE__ */
 203
 204 #include "ace/Module.cpp"
 205
 206 #include /**/ "ace/post.h"
 207
 208 #endif /* ACE_MODULE_H */