TAO/tao/CSD_ThreadPool/CSD_TP_Strategy.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    CSD_TP_Strategy.h
   6  *
   7  *  @author  Tim Bradley <bradley_t@ociweb.com>
   8  */
   9 //=============================================================================
  10
  11 #ifndef TAO_CSD_TP_STRATEGY_H
  12 #define TAO_CSD_TP_STRATEGY_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include "tao/CSD_ThreadPool/CSD_TP_Export.h"
  17
  18 #include "tao/CSD_ThreadPool/CSD_TP_Task.h"
  19 #include "tao/CSD_ThreadPool/CSD_TP_Servant_State_Map.h"
  20
  21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  22 # pragma once
  23 #endif /* ACE_LACKS_PRAGMA_ONCE */
  24
  25 #include "tao/CSD_Framework/CSD_Strategy_Base.h"
  26 #include "tao/Intrusive_Ref_Count_Handle_T.h"
  27
  28
  29 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  30
  31 namespace TAO
  32 {
  33   namespace CSD
  34   {
  35     class TP_Strategy;
  36     typedef TAO_Intrusive_Ref_Count_Handle<TP_Strategy> TP_Strategy_Handle;
  37
  38     class TP_Custom_Request_Operation;
  39
  40     /**
  41      * @class TP_Strategy
  42      *
  43      * @brief A simple custom Thread-Pool servant dispatching strategy class.
  44      *
  45      * This class represents a concrete implementation of a "Custom
  46      * Servant Dispatching Strategy".  This implementation is being called
  47      * the "Thread Pool Strategy" reference implementation.
  48      *
  49      * A custom servant dispatching strategy object can be applied to a
  50      * POA object in order to carry out the servant dispatching duties
  51      * for that POA.
  52      *
  53      */
  54     class TAO_CSD_TP_Export TP_Strategy
  55       : public Strategy_Base
  56     {
  57     public:
  58       /// Constructor.
  59       TP_Strategy(Thread_Counter  num_threads = 1,
  60                   bool     serialize_servants = true);
  61
  62       /// Virtual Destructor.
  63       virtual ~TP_Strategy();
  64
  65       /// Set the number of threads in the pool (must be > 0).
  66       void set_num_threads(Thread_Counter num_threads);
  67
  68       /// Turn on/off serialization of servants.
  69       void set_servant_serialization(bool serialize_servants);
  70
  71       /// Return codes for the custom dispatch_request() methods.
  72       enum CustomRequestOutcome
  73       {
  74         /// The request was successfully put on the request queue.
  75         REQUEST_DISPATCHED,
  76         /// The request has been executed/completed by a worker thread.
  77         REQUEST_EXECUTED,
  78         /// The request was removed from the queue and cancelled.
  79         REQUEST_CANCELLED,
  80         /// The request queue rejected the request
  81         REQUEST_REJECTED
  82       };
  83
  84       /// Inject a synchronous, custom request into the request queue.
  85       /// This will block the calling thread until the request is handled
  86       /// (dispatched or cancelled) or rejected.
  87       /// Will return REQUEST_EXECUTED, REQUEST_CANCELLED, or REQUEST_REJECTED.
  88       CustomRequestOutcome custom_synch_request
  89                                         (TP_Custom_Request_Operation* op);
  90
  91       /// Inject an asynchronous, custom request into the request queue.
  92       /// This will return control to the calling thread once the request
  93       /// has been placed into the queue (or rejected).
  94       /// Will return REQUEST_DISPATCHED or REQUEST_REJECTED.
  95       CustomRequestOutcome custom_asynch_request
  96                                          (TP_Custom_Request_Operation* op);
  97
  98       /// Cancel all requests that are targeted for the provided servant.
  99       /// This is requested on the user application level.
 100       void cancel_requests(PortableServer::Servant servant);
 101
 102     protected:
 103       /// Handle the dispatching of a remote request.
 104       ///
 105       /// This will cause a new "request" object to be created and pushed
 106       /// on to a "request queue".  The worker threads are responsible for
 107       /// servicing the queue, and performing the actual dispatch logic.
 108       virtual Strategy_Base::DispatchResult dispatch_remote_request_i
 109                              (TAO_ServerRequest&              server_request,
 110                               const PortableServer::ObjectId& object_id,
 111                               PortableServer::POA_ptr         poa,
 112                               const char*                     operation,
 113                               PortableServer::Servant         servant);
 114
 115       /// Handle the dispatching of a collocated request.
 116       ///
 117       /// This will cause a new "request" object to be created and pushed
 118       /// on to a "request queue".  The worker threads are responsible for
 119       /// servicing the queue, and performing the actual dispatch logic.
 120       virtual Strategy_Base::DispatchResult dispatch_collocated_request_i
 121                              (TAO_ServerRequest&              server_request,
 122                               const PortableServer::ObjectId& object_id,
 123                               PortableServer::POA_ptr         poa,
 124                               const char*                     operation,
 125                               PortableServer::Servant         servant);
 126
 127       /// Event - The POA has been activated.
 128       /// This will activate the worker thread(s).
 129       /// Returns true if the worker threads were activated successfully.
 130       /// Otherwise, returns false.
 131       virtual bool poa_activated_event_i(TAO_ORB_Core& orb_core);
 132
 133       /// Event - The POA has been deactivated.
 134       /// This will shutdown the worker thread(s).
 135       virtual void poa_deactivated_event_i();
 136
 137       /// Event - A servant has been activated
 138       virtual void servant_activated_event_i
 139                                      (PortableServer::Servant servant,
 140                                       const PortableServer::ObjectId& oid);
 141
 142       /// Event - A servant has been deactivated
 143       virtual void servant_deactivated_event_i
 144                                     (PortableServer::Servant servant,
 145                                      const PortableServer::ObjectId& oid);
 146
 147     private:
 148       /**
 149       * Helper method that is responsible for looking up the servant
 150       * state object in the servant state map *if* the "serialize
 151       * servants" flag is set to true.  In the case where the
 152       * "serialize servants" flag is set to false, then a "nil"
 153       * servant state handle object is returned.
 154       *
 155       * @param servant - input - a pointer to the servant object.
 156       *
 157       * @returns a handle to a servant state object.
 158       *
 159       * @throw PortableServer::POA::ServantNotActive if the servant
 160       *        state cannot be determined.
 161       */
 162       TP_Servant_State::HandleType get_servant_state
 163                                       (PortableServer::Servant servant);
 164
 165
 166       /// This is the active object used by the worker threads.
 167       /// The request queue is owned/managed by the task object.
 168       /// The strategy object puts requests into the task's request
 169       /// queue, and the worker threads service the queued requests
 170       /// by performing the actual servant request dispatching logic.
 171       TP_Task task_;
 172
 173       /// The number of worker threads to use for the task.
 174       Thread_Counter num_threads_;
 175
 176       /// The "serialize servants" flag.
 177       bool serialize_servants_;
 178
 179       /// The map of servant state objects - only used when the
 180       /// "serialize servants" flag is set to true.
 181       TP_Servant_State_Map servant_state_map_;
 182     };
 183   }
 184 }
 185
 186 TAO_END_VERSIONED_NAMESPACE_DECL
 187
 188 #if defined (__ACE_INLINE__)
 189 # include "tao/CSD_ThreadPool/CSD_TP_Strategy.inl"
 190 #endif /* __ACE_INLINE__ */
 191
 192 #include /**/ "ace/post.h"
 193
 194 #endif /* TAO_CSD_TP_STRATEGY_H */