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