From 3d6b76128175a6fe3358c00f072067d863e0adac Mon Sep 17 00:00:00 2001 From: bala Date: Sun, 2 Nov 2003 21:41:45 +0000 Subject: ChangeLogTag:Sun Nov 2 15:45:55 2003 Balachandran Natarajan --- TAO/ChangeLog | 15 +++++ TAO/tao/Collocated_Invocation.h | 33 +++++++++- TAO/tao/Invocation_Adapter.cpp | 2 - TAO/tao/Invocation_Adapter.h | 2 +- TAO/tao/Invocation_Base.h | 30 +++++---- TAO/tao/LocateRequest_Invocation.h | 29 +++++++-- TAO/tao/LocateRequest_Invocation_Adapter.cpp | 18 +++--- TAO/tao/LocateRequest_Invocation_Adapter.h | 19 +++++- TAO/tao/Remote_Invocation.cpp | 11 ++-- TAO/tao/Remote_Invocation.h | 22 ++++++- TAO/tao/Synch_Invocation.h | 95 +++++++++++++++++++++++++--- 11 files changed, 228 insertions(+), 48 deletions(-) diff --git a/TAO/ChangeLog b/TAO/ChangeLog index 44331bc1aae..2329813d31f 100644 --- a/TAO/ChangeLog +++ b/TAO/ChangeLog @@ -1,3 +1,18 @@ +Sun Nov 2 15:45:55 2003 Balachandran Natarajan + + * tao/Collocated_Invocation.h: + * tao/Invocation_Adapter.cpp: + * tao/Invocation_Adapter.h: + * tao/Invocation_Base.h: + * tao/LocateRequest_Invocation.h: + * tao/LocateRequest_Invocation_Adapter.cpp: + * tao/LocateRequest_Invocation_Adapter.h: + * tao/Remote_Invocation.cpp: + * tao/Remote_Invocation.h: + * tao/Synch_Invocation.h: + + Added and improved doxygen documentation. + Sat Nov 1 14:58:02 2003 Balachandran Natarajan * tao/Sync_Strategies.cpp: diff --git a/TAO/tao/Collocated_Invocation.h b/TAO/tao/Collocated_Invocation.h index 93fba967dce..9278ea97f40 100644 --- a/TAO/tao/Collocated_Invocation.h +++ b/TAO/tao/Collocated_Invocation.h @@ -37,20 +37,49 @@ namespace TAO /** * @class Collocated_Invocation * - * @brief Base class for .. + * @brief Class for Collocated invocations * * @NOTE: Reliable oneways are not handled properly including use of - * interceptors. + * interceptors. This class should technically serve as the base + * for all invocation types. But now, this is the only class that + * handles collocated invocations and that too in a brain dead way. */ class TAO_Export Collocated_Invocation : public Invocation_Base { public: + /// Constructor used by TAO::Invocation_Adapter + /** + * @param et, The effective target in which this invocation is now + * flowing + * + * @param t, The target on which invocation first started. + * + * @param stub, Stub for target @t + * + * @param detail, operation details of the invocation including + * the service context list + * + * @param response_expected, flag to indicate whether the + * operation encapsulated by @a detail returns a response or not. + */ Collocated_Invocation (CORBA::Object_ptr et, CORBA::Object_ptr t, TAO_Stub *stub, TAO_Operation_Details &detail, bool response_expected = true); + /// Invocation on the collocated object mediated through this + /// class. + /** + * Practically this method is a place holder to do the + * following + * - Call the start and end interception points on the client + * side. + * + * - Handle location forwards that could be thrown by the + * servant. + * + */ Invocation_Status invoke (Collocation_Proxy_Broker *cpb, Collocation_Strategy strat ACE_ENV_ARG_DECL) diff --git a/TAO/tao/Invocation_Adapter.cpp b/TAO/tao/Invocation_Adapter.cpp index 4ffb4656e3d..1ac723d54b4 100644 --- a/TAO/tao/Invocation_Adapter.cpp +++ b/TAO/tao/Invocation_Adapter.cpp @@ -88,8 +88,6 @@ namespace TAO if (strat == TAO_CS_REMOTE_STRATEGY || strat == TAO_CS_LAST) { - - status = this->invoke_remote_i (stub, details, diff --git a/TAO/tao/Invocation_Adapter.h b/TAO/tao/Invocation_Adapter.h index d3302778bbd..9ba0db72756 100644 --- a/TAO/tao/Invocation_Adapter.h +++ b/TAO/tao/Invocation_Adapter.h @@ -110,7 +110,7 @@ namespace TAO TAO::Invocation_Type type = TAO_TWOWAY_INVOCATION, TAO::Invocation_Mode mode = TAO_SYNCHRONOUS_INVOCATION); - /// Invoke the target + /// Invoke the target, and used by the generated code. /** * The implementation decides whether the target is remote or * collocated and takes the right decision. diff --git a/TAO/tao/Invocation_Base.h b/TAO/tao/Invocation_Base.h index cbf69e0430d..95b61f9cbdd 100644 --- a/TAO/tao/Invocation_Base.h +++ b/TAO/tao/Invocation_Base.h @@ -50,14 +50,14 @@ namespace TAO * * This class is the base of the invocation object hiererachy. This * hierarchy is classified based on the type of invocation and the - * mode of the invocation. One of the objects from the hiererachy is + * mode of invocation. One of the objects from the hiererachy is * created on the stack for every invocation. * - * This class encapsulates the essential details that are required - * for PortableInterceptors to function correctly. Further this - * class also provides some helper and accessor methods that are - * used by clients. - * @@ More.. + * In addition this class encapsulates the essential details that + * are required for PortableInterceptors to function + * correctly. Further this class also provides some helper and + * accessor methods that are used by clients. + * */ class TAO_Export Invocation_Base { @@ -65,7 +65,7 @@ namespace TAO virtual ~Invocation_Base (void); //@{ - /// Accessor and mutator methods .. + /// Accessor and mutator methods TAO_ORB_Core *orb_core (void) const; TAO_Stub *stub (void) const; @@ -73,13 +73,18 @@ namespace TAO /// Accessor and mutator methods for forwarded object /// locations. /** - * These methods have to be public so that the PortableInterceptor - * can use this. + * These access methods have to be public so that the + * PortableInterceptor can use them */ CORBA::Object_ptr forwarded_reference (void); void forwarded_reference (CORBA::Object_ptr o); - /// Accessors for the service context list + /// Accessors for the service context list. + /** + * The service context lists are actually cached + * elsewhere. Providing this accessor helps the PI to access this + * list in both remote and collocated mode. + */ TAO_Service_Context &request_service_context (void); TAO_Service_Context &reply_service_context (void); @@ -104,10 +109,9 @@ namespace TAO /// Does this invocation return a response? CORBA::Boolean response_expected (void) const; - //@} + protected: - /// Don't allow creation of an object of type Invocation_Base. /** * @param otarget, The original target on which this invocation * was started. @@ -133,7 +137,7 @@ namespace TAO /// Forwarded object reference. CORBA::Object_var forwarded_to_; - /// Is the response expected? + /// Is response expected? bool response_expected_; private: diff --git a/TAO/tao/LocateRequest_Invocation.h b/TAO/tao/LocateRequest_Invocation.h index 3b664f1c43a..0d8df08b517 100644 --- a/TAO/tao/LocateRequest_Invocation.h +++ b/TAO/tao/LocateRequest_Invocation.h @@ -34,20 +34,41 @@ namespace TAO { class Profile_Transport_Resolver; + /** + * @class LocateRequest_Invocation + * + * @brief Object created bu TAO::LocateRequest_Invocation_Adapter to + * create and send LocateRequest invocation. + * + */ class TAO_Export LocateRequest_Invocation : protected Synch_Twoway_Invocation { public: - LocateRequest_Invocation (CORBA::Object_ptr otarget, - Profile_Transport_Resolver &resolver, - TAO_Operation_Details &detail); + /** + * @param target, The target on which this invocation was + * started. + * + * @param resolver, Comntainer of the profile and transport on + * which this invocation is on + * + * @param detail, Operation details of the invocation on @a + * target. This is of no practical importance since it is not used + * in this class. This is just to keep our base class happy. + * + */ + LocateRequest_Invocation ( + CORBA::Object_ptr otarget, + Profile_Transport_Resolver &resolver, + TAO_Operation_Details &detail); + /// Start the invocation. Invocation_Status invoke (ACE_Time_Value *max_wait_time ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::Exception)); private: - + /// Helper to check the reply status Invocation_Status check_reply (TAO_Synch_Reply_Dispatcher &rd ACE_ENV_ARG_DECL); diff --git a/TAO/tao/LocateRequest_Invocation_Adapter.cpp b/TAO/tao/LocateRequest_Invocation_Adapter.cpp index 332e9e79dee..20dd2f48720 100644 --- a/TAO/tao/LocateRequest_Invocation_Adapter.cpp +++ b/TAO/tao/LocateRequest_Invocation_Adapter.cpp @@ -19,7 +19,7 @@ namespace TAO { } - bool + void LocateRequest_Invocation_Adapter::invoke (ACE_ENV_SINGLE_ARG_DECL) { CORBA::Object *effective_target = this->target_; @@ -28,12 +28,11 @@ namespace TAO this->target_->_stubobj (); if (stub == 0) - ACE_THROW_RETURN (CORBA::INTERNAL ( - CORBA::SystemException::_tao_minor_code ( - TAO_DEFAULT_MINOR_CODE, - EINVAL), - CORBA::COMPLETED_NO), - 0); + ACE_THROW (CORBA::INTERNAL ( + CORBA::SystemException::_tao_minor_code ( + TAO_DEFAULT_MINOR_CODE, + EINVAL), + CORBA::COMPLETED_NO)); ACE_Time_Value tmp_wait_time; ACE_Time_Value *max_wait_time = 0; @@ -44,7 +43,6 @@ namespace TAO if (is_timeout) max_wait_time = &tmp_wait_time; - Invocation_Status s = TAO_INVOKE_START; while (s == TAO_INVOKE_START || @@ -89,10 +87,10 @@ namespace TAO ACE_RE_THROW; } ACE_ENDTRY; - ACE_CHECK_RETURN (false); + ACE_CHECK; } - return true; + return; } CORBA::PolicyList * diff --git a/TAO/tao/LocateRequest_Invocation_Adapter.h b/TAO/tao/LocateRequest_Invocation_Adapter.h index 790c0bc284d..59220809fd9 100644 --- a/TAO/tao/LocateRequest_Invocation_Adapter.h +++ b/TAO/tao/LocateRequest_Invocation_Adapter.h @@ -29,16 +29,31 @@ namespace CORBA namespace TAO { /** + * @class LocateRequest_Invocation_Adapter * + * @brief Adapter class for locate request invocations. * + * This class provides a look and feel similar to the + * TAO::Invocation_Adapter though the functionalities are + * different. For the record, IDL compiler doesn't know the + * existence of this class. This class is concerned with the + * creation and invocation of locate request invocations to the + * target object + * + * @todo: Need to think what happens if the target is + * collocated. Looks like there are no ways to utilize the + * opportunity that may have been presented. */ class TAO_Export LocateRequest_Invocation_Adapter { public: - LocateRequest_Invocation_Adapter (CORBA::Object_ptr target); + LocateRequest_Invocation_Adapter ( + CORBA::Object_ptr target); - bool invoke (ACE_ENV_SINGLE_ARG_DECL); + /// Start the invocation on the target + void invoke (ACE_ENV_SINGLE_ARG_DECL); + /// Accessor to the inconsistent policy list CORBA::PolicyList *get_inconsistent_policies (void); private: diff --git a/TAO/tao/Remote_Invocation.cpp b/TAO/tao/Remote_Invocation.cpp index 475b51f35f2..97377e5371f 100644 --- a/TAO/tao/Remote_Invocation.cpp +++ b/TAO/tao/Remote_Invocation.cpp @@ -14,10 +14,12 @@ ACE_RCSID (tao, namespace TAO { - Remote_Invocation::Remote_Invocation (CORBA::Object_ptr otarget, - Profile_Transport_Resolver &resolver, - TAO_Operation_Details &detail, - bool response_expected) + Remote_Invocation::Remote_Invocation ( + CORBA::Object_ptr otarget, + Profile_Transport_Resolver &resolver, + TAO_Operation_Details &detail, + bool response_expected) + : Invocation_Base (otarget, resolver.object (), resolver.stub (), @@ -31,7 +33,6 @@ namespace TAO Remote_Invocation::init_target_spec (TAO_Target_Specification &target_spec ACE_ENV_ARG_DECL) { - /** * Mega hack for RTCORBA start. I don't think that * PortableInterceptor would work here esp. for RTCORBA. PI needs diff --git a/TAO/tao/Remote_Invocation.h b/TAO/tao/Remote_Invocation.h index 61638659a53..383691acddd 100644 --- a/TAO/tao/Remote_Invocation.h +++ b/TAO/tao/Remote_Invocation.h @@ -40,12 +40,27 @@ namespace TAO /** * @class Remote_Invocation * - * @brief Base class for Twoway_Invocation and Oneway_Invocation. + * @brief Base class for remote invocations. + * + * This class encapulates some of the common functionalities used by + * synchronous, asynchronous, DII and DSI invocations. * */ class TAO_Export Remote_Invocation : public Invocation_Base { public: + /** + * @param otarget, The original target on which this invocation + * was started. This is there to be passed up to its parent + * class. + * + * @param resolver, The profile and transport holder. + * + * @param op, operation details of the invocation on the target + * + * @param response_expected, flag to indicate whether the + * operation encapsulated by @a op returns a response or not. + */ Remote_Invocation (CORBA::Object_ptr otarget, Profile_Transport_Resolver &resolver, TAO_Operation_Details &detail, @@ -53,22 +68,27 @@ namespace TAO protected: + /// Initialize the @a spec. void init_target_spec (TAO_Target_Specification &spec ACE_ENV_ARG_DECL); + /// Write the GIOP header into the stream. void write_header (TAO_Target_Specification &spec, TAO_OutputCDR &out_stream ACE_ENV_ARG_DECL); + /// Marshal the arguments into the stream. void marshal_data (TAO_OutputCDR &cdr ACE_ENV_ARG_DECL); + /// Write the message onto the socket Invocation_Status send_message (TAO_OutputCDR &cdr, short message_semantics, ACE_Time_Value *max_wait_time ACE_ENV_ARG_DECL); protected: + /// Our resolver Profile_Transport_Resolver &resolver_; }; } diff --git a/TAO/tao/Synch_Invocation.h b/TAO/tao/Synch_Invocation.h index 68aaeb2c8af..7346e3de91d 100644 --- a/TAO/tao/Synch_Invocation.h +++ b/TAO/tao/Synch_Invocation.h @@ -38,14 +38,49 @@ namespace TAO { class Profile_Transport_Resolver; + /** + * @class Synch_Twoway_Invocation + * + * @brief All the action for a synchronous twoway invocation happen + * here. + * + * An object of this is type is created by TAO::Invocation_Adapter + * and invokes a method on this class. The method takes care of + * creating and sending a request, waiting for a reply and + * demarshalling the reply for the client. + * + */ class TAO_Export Synch_Twoway_Invocation : public Remote_Invocation { public: + /// Constructor used by TAO::Invocation_Adapter + /** + * @param otarget, The original target on which this invocation + * was started. This is there to be passed up to its parent + * class. + * + * @param resolver, The profile and transport holder. + * + * @param op, operation details of the invocation on the target + * + * @param response_expected, flag to indicate whether the + * operation encapsulated by @a op returns a response or not. + */ Synch_Twoway_Invocation (CORBA::Object_ptr otarget, Profile_Transport_Resolver &resolver, TAO_Operation_Details &detail, bool response_expected = true); + /// Method used by the adapter to kickstart an invocation to the + /// remote object. + /** + * There is a exception declaration in this method which ensures + * that the exceptions propogated by the remote objects are + * converted a CORBA exceptions for the clients. This method does + * a bunch of things necessary to create and send the + * invocation. This method is also nerve centre for the + * interceptor invocation points. + */ Invocation_Status remote_twoway (ACE_Time_Value *max_wait_time ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::Exception)); @@ -62,57 +97,101 @@ namespace TAO ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::Exception)); + /// Helper method used to handle location forwarded replies. Invocation_Status location_forward (TAO_InputCDR &cdr ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::SystemException)); - - + /// Helper method used to handle system exceptions from the remote + /// objects. Invocation_Status handle_system_exception (TAO_InputCDR &cdr ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::SystemException)); + /// As the name suggests waits for a reply from the remote ORB. Invocation_Status wait_for_reply (ACE_Time_Value *max_wait_time, TAO_Synch_Reply_Dispatcher &rd, TAO_Bind_Dispatcher_Guard &bd ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::SystemException)); - private: - Invocation_Status check_reply_status (TAO_Synch_Reply_Dispatcher &rd - ACE_ENV_ARG_DECL); - + /// Helper method that checks the reply status of the + /// replies and takes appropriate action. + Invocation_Status check_reply_status ( + TAO_Synch_Reply_Dispatcher &rd + ACE_ENV_ARG_DECL); }; - class TAO_Export Synch_Oneway_Invocation : public Synch_Twoway_Invocation + /** + * @class Synch_Oneway_Invocation + * + * @brief All the action for a synchronous oneway invocation happen + * here. + * + * This class inherits from twoway invocation for the following + * reasons + * + * - We deal with oneway invocation in more or less the same way as + * two but for waiting for the reply + * + * - For some SYNC_SCOPE policies namely SYNC_WITH_TARGET and + * SYNC_WITH_SERVER the invocation classes have to treat the + * invocation as a twoway invocation (more or less) + * + */ + class TAO_Export Synch_Oneway_Invocation : + public Synch_Twoway_Invocation { public: + /// Constructor used by TAO::Invocation_Adapter + /** + * @param otarget, The original target on which this invocation + * was started. This is there to be passed up to its parent + * class. + * + * @param resolver, The profile and transport holder. + * + * @param op, operation details of the invocation on the target + * + * @param response_expected, flag to indicate whether the + * operation encapsulated by @a op returns a response or not. + */ Synch_Oneway_Invocation (CORBA::Object_ptr otarget, Profile_Transport_Resolver &resolver, TAO_Operation_Details &detail); + /// Method used by the adapter to kickstart an oneway invocation + /// to the remote object. Invocation_Status remote_oneway (ACE_Time_Value *max_wait_time ACE_ENV_ARG_DECL) ACE_THROW_SPEC ((CORBA::Exception)); }; + /** + * @class Reply_Guard + * + * @brief A guard class used for storing and forwarding the reply + * status to the portable interceptors. + */ class TAO_Export Reply_Guard { public: Reply_Guard (Invocation_Base *s, Invocation_Status is); + /// The destructor calls Invocation_Base::reply_received with the + /// right reply status, which is useful for PI's. ~Reply_Guard (void); + /// Mutator to set the invocation status. void set_status (Invocation_Status s); private: Invocation_Base *invocation_; Invocation_Status status_; - }; } -- cgit v1.2.1