TAO/tao/ORB.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    ORB.h
   6  *
   7  *  Header file for CORBA's ORB type.
   8  *
   9  *  @author DOC Center - Washington University at St. Louis
  10  *  @author DOC Group - Vanderbilt University
  11  *  @author DOC Laboratory - University of California at Irvine
  12  */
  13 //=============================================================================
  14
  15 #ifndef TAO_ORB_H
  16 #define TAO_ORB_H
  17
  18 #include /**/ "ace/pre.h"
  19
  20 #include "tao/UserException.h"
  21
  22 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  23 # pragma once
  24 #endif /* ACE_LACKS_PRAGMA_ONCE */
  25
  26 #include "tao/orb_typesC.h"
  27 #include "tao/objectid.h"
  28 #include "tao/VarOut_T.h"
  29 #include "tao/Pseudo_VarOut_T.h"
  30 #include "tao/Seq_Var_T.h"
  31 #include "tao/Seq_Out_T.h"
  32 #include "tao/Sequence_T.h"
  33 #include "tao/Policy_ForwardC.h"
  34 #include "tao/ServicesC.h"
  35
  36 #include "ace/Thread_Mutex.h"
  37 #include "ace/Guard_T.h"
  38 #include <atomic>
  39
  40 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  41
  42 typedef enum
  43 {
  44   TAO_SERVICEID_NAMESERVICE,
  45   TAO_SERVICEID_TRADINGSERVICE,
  46   TAO_SERVICEID_IMPLREPOSERVICE,
  47   TAO_SERVICEID_INTERFACEREPOSERVICE,
  48   TAO_SERVICEID_MCASTSERVER
  49 } TAO_Service_ID;
  50
  51 /// Forward declarations.
  52 class TAO_MProfile;
  53 class TAO_Client_Strategy_Factory;
  54 class TAO_Server_Strategy_Factory;
  55 class TAO_InputCDR;
  56 class TAO_OutputCDR;
  57 class TAO_Stub;
  58 class TAO_Valuetype_Adapter;
  59 class TAO_Acceptor_Filter;
  60 class TAO_ORB_Core;
  61
  62 // ****************************************************************
  63
  64 namespace CORBA
  65 {
  66   class EnumMemberSeq;
  67   class StructMemberSeq;
  68   class UnionMemberSeq;
  69   class ValueMemberSeq;
  70   class ORB_ObjectIdList;
  71
  72   class Object;
  73   typedef Object * Object_ptr;
  74
  75   class ExceptionList;
  76   typedef ExceptionList * ExceptionList_ptr;
  77
  78   class ContextList;
  79   typedef ContextList * ContextList_ptr;
  80
  81   class Context;
  82   typedef Context * Context_ptr;
  83
  84   class NVList;
  85   typedef NVList *NVList_ptr;
  86
  87   class NamedValue;
  88   typedef NamedValue *NamedValue_ptr;
  89
  90   class Policy;
  91   typedef Policy *Policy_ptr;
  92
  93   class OperationDef;
  94   typedef OperationDef * OperationDef_ptr;
  95
  96   typedef CORBA::ULong PolicyType;
  97
  98   // TODO - implement OMG's 'ORBid CORBA::ORB::id ()'.
  99
 100   typedef
 101     TAO_VarSeq_Var_T<
 102         ORB_ObjectIdList
 103       >
 104     ORB_ObjectIdList_var;
 105
 106   typedef
 107     TAO_Seq_Out_T<
 108         ORB_ObjectIdList
 109       >
 110     ORB_ObjectIdList_out;
 111
 112   class ValueFactoryBase;
 113   typedef ValueFactoryBase *ValueFactory;
 114
 115   typedef UShort ServiceType;
 116
 117   class Request;
 118   typedef Request * Request_ptr;
 119   typedef TAO_Pseudo_Var_T<Request> Request_var;
 120   typedef TAO_Pseudo_Out_T<Request> Request_out;
 121
 122   class ORB;
 123   typedef ORB * ORB_ptr;
 124   typedef TAO_Pseudo_Var_T<ORB> ORB_var;
 125   typedef TAO_Pseudo_Out_T<ORB> ORB_out;
 126
 127   typedef CORBA::Short ValueModifier;
 128
 129 #if (TAO_HAS_MINIMUM_CORBA == 0) && !defined (CORBA_E_COMPACT) && !defined (CORBA_E_MICRO)
 130
 131     // Typedefs for CORBA::RequestSeq, which is an argument of
 132     // send_multiple_requests_*().
 133     typedef
 134       TAO::unbounded_object_reference_sequence<
 135           CORBA::Request, CORBA::Request_var
 136         >
 137       RequestSeq;
 138
 139     typedef
 140       TAO_VarSeq_Var_T<
 141           RequestSeq
 142         >
 143       RequestSeq_var;
 144
 145     typedef
 146       TAO_Seq_Out_T<
 147           RequestSeq
 148         >
 149       RequestSeq_out;
 150 #endif
 151
 152   /**
 153    * @class ORB
 154    *
 155    * @brief ORB pseudo-object.
 156    *
 157    * The "ORB" pseudo-object is used in bootstrapping, such as to
 158    * create object references from strings.  This class is intended
 159    * to be inherited by others, which will provide some more of the
 160    * CORBA support.  Implementations of this "CORBA::ORB" class must
 161    * know how to create stringify/destringify their objrefs, as well
 162    * as how to marshal and unmarshal them.
 163    */
 164   class TAO_Export ORB
 165   {
 166   public:
 167     class TAO_Export InvalidName : public CORBA::UserException
 168     {
 169     public:
 170       InvalidName ();
 171       InvalidName (const InvalidName &);
 172       ~InvalidName ();
 173
 174       InvalidName &operator= (const InvalidName &);
 175
 176       static InvalidName *_downcast (CORBA::Exception *);
 177       static CORBA::Exception *_alloc ();
 178
 179       virtual CORBA::Exception *_tao_duplicate () const;
 180
 181       virtual void _raise () const;
 182
 183       virtual void _tao_encode (TAO_OutputCDR &) const;
 184
 185       virtual void _tao_decode (TAO_InputCDR &);
 186     };
 187
 188     typedef char *ObjectId;
 189     typedef CORBA::String_var ObjectId_var;
 190     typedef CORBA::String_out ObjectId_out;
 191     static CORBA::TypeCode_ptr const _tc_ObjectId;
 192
 193     typedef CORBA::ORB_ObjectIdList ObjectIdList;
 194     typedef CORBA::ORB_ObjectIdList_var ObjectIdList_var;
 195     typedef CORBA::ORB_ObjectIdList_out ObjectIdList_out;
 196     typedef CORBA::ORB_ObjectIdList *ObjectIdList_ptr;
 197     static CORBA::TypeCode_ptr const _tc_ObjectIdList;
 198
 199     /// Return a duplicate of @c orb.
 200     /**
 201      * When work with this duplicate is complete, it should be freed
 202      * up using CORBA::release().
 203      */
 204     static CORBA::ORB_ptr _duplicate (CORBA::ORB_ptr orb);
 205
 206     /// Returns a pointer to a nil ORB, i.e., an non-existent ORB.  This
 207     /// can be used for initialization or in comparisons.
 208     static CORBA::ORB_ptr _nil ();
 209
 210     /// Return this ORB's ORBid.
 211     char * id ();
 212
 213     /**
 214      * Turn a string-ified object reference back into an object
 215      * pointer.  Typically these strings are created using
 216      * object_to_string(), but not necessarily locally.
 217      */
 218     CORBA::Object_ptr string_to_object (const char *str);
 219
 220 #if defined (ACE_USES_WCHAR)
 221     /**
 222      * Turn a string-ified object reference back into an object
 223      * pointer.  Typically these strings are created using
 224      * object_to_string(), but not necessarily locally.
 225      * This is a TAO specific extension.
 226      */
 227     CORBA::Object_ptr string_to_object (const wchar_t *str);
 228 #endif
 229     /**
 230      * Turn an object reference into a string.  Each type of ORB,
 231      * e.g. an IIOP ORB, must implement this.  This can be used by
 232      * servers to publish their whereabouts to clients.  The output of
 233      * this is typically eventually given to @c string_to_object() as
 234      * an argument.
 235      */
 236     char * object_to_string (CORBA::Object_ptr obj);
 237
 238 #if !defined(CORBA_E_MICRO)
 239     // Value factory operations  (CORBA 2.3 ptc/98-10-05 Ch. 4.2 p.4-7)
 240     CORBA::ValueFactory register_value_factory (
 241         const char *repository_id,
 242         CORBA::ValueFactory factory);
 243 #endif
 244
 245 #if !defined(CORBA_E_MICRO)
 246     void unregister_value_factory (const char * repository_id);
 247 #endif
 248
 249 #if !defined(CORBA_E_MICRO)
 250     CORBA::ValueFactory lookup_value_factory (const char *repository_id);
 251 #endif
 252
 253 #if (TAO_HAS_MINIMUM_CORBA == 0) && !defined (CORBA_E_COMPACT) && !defined (CORBA_E_MICRO)
 254
 255     void create_list (CORBA::Long count, CORBA::NVList_ptr &new_list);
 256
 257     void create_operation_list(CORBA::OperationDef_ptr opDef,
 258                                CORBA::NVList_ptr& result);
 259
 260     void create_named_value (CORBA::NamedValue_ptr &nmval);
 261
 262     void create_exception_list (CORBA::ExceptionList_ptr &exclist);
 263
 264     void create_environment (CORBA::Environment_ptr &new_env);
 265
 266     // The following are not implemented and just throw
 267     // CORBA::NO_IMPLEMENT.
 268
 269     void create_context_list (CORBA::ContextList_ptr &ctxtlist);
 270
 271     void get_default_context (CORBA::Context_ptr &ctx);
 272
 273     CORBA::Boolean get_service_information (
 274       CORBA::ServiceType service_type,
 275       CORBA::ServiceInformation_out service_information);
 276
 277     void send_multiple_requests_oneway (const CORBA::RequestSeq &req);
 278
 279     void send_multiple_requests_deferred (const CORBA::RequestSeq &req);
 280
 281     void get_next_response (CORBA::Request_ptr &req);
 282
 283     CORBA::Boolean poll_next_response ();
 284
 285     /// The ORB TypeCode creation functions.
 286
 287     CORBA::TypeCode_ptr create_struct_tc (
 288         const char *id,
 289         const char *name,
 290         const CORBA::StructMemberSeq &members);
 291
 292     CORBA::TypeCode_ptr create_union_tc (
 293         const char *id,
 294         const char *name,
 295         CORBA::TypeCode_ptr discriminator_type,
 296         const CORBA::UnionMemberSeq &members);
 297
 298     CORBA::TypeCode_ptr create_enum_tc (
 299         const char *id,
 300         const char *name,
 301         const CORBA::EnumMemberSeq &members);
 302
 303     CORBA::TypeCode_ptr create_alias_tc (
 304         const char *id,
 305         const char *name,
 306         CORBA::TypeCode_ptr original_type);
 307
 308     CORBA::TypeCode_ptr create_exception_tc (
 309         const char *id,
 310         const char *name,
 311         const CORBA::StructMemberSeq &members);
 312
 313     CORBA::TypeCode_ptr create_interface_tc (const char *id, const char *name);
 314
 315     CORBA::TypeCode_ptr create_string_tc (CORBA::ULong bound);
 316
 317     CORBA::TypeCode_ptr create_wstring_tc (CORBA::ULong bound);
 318
 319     CORBA::TypeCode_ptr create_fixed_tc (
 320         CORBA::UShort digits,
 321         CORBA::UShort scale);
 322
 323     CORBA::TypeCode_ptr create_sequence_tc (
 324         CORBA::ULong bound,
 325         CORBA::TypeCode_ptr element_type);
 326
 327     CORBA::TypeCode_ptr create_array_tc (
 328         CORBA::ULong length,
 329         CORBA::TypeCode_ptr element_type);
 330
 331     CORBA::TypeCode_ptr create_value_tc (
 332         const char *id,
 333         const char *name,
 334         CORBA::ValueModifier type_modifier,
 335         CORBA::TypeCode_ptr concrete_base,
 336         const CORBA::ValueMemberSeq &members);
 337
 338     CORBA::TypeCode_ptr create_value_box_tc (
 339         const char *id,
 340         const char *name,
 341         CORBA::TypeCode_ptr boxed_type);
 342
 343     CORBA::TypeCode_ptr create_native_tc (const char *id, const char *name);
 344
 345     CORBA::TypeCode_ptr create_recursive_tc (const char *id);
 346
 347     CORBA::TypeCode_ptr create_abstract_interface_tc (
 348         const char *id,
 349         const char *name);
 350
 351     CORBA::TypeCode_ptr create_local_interface_tc (
 352         const char *id,
 353         const char *name);
 354
 355     CORBA::TypeCode_ptr create_component_tc (
 356         const char *id,
 357         const char *name);
 358
 359     CORBA::TypeCode_ptr create_home_tc (
 360         const char *id,
 361         const char *name);
 362
 363     CORBA::TypeCode_ptr create_event_tc (
 364         const char *id,
 365         const char *name,
 366         CORBA::ValueModifier type_modifier,
 367         CORBA::TypeCode_ptr concrete_base,
 368         const CORBA::ValueMemberSeq &members);
 369
 370 #endif /* TAO_HAS_MINIMUM_CORBA */
 371
 372     // = ORB event loop methods.
 373
 374     /**
 375      * Instructs the ORB to initialize itself and run its event loop in
 376      * the current thread, not returning until the ORB has shut down.
 377      * If an error occurs during initialization or at runtime, a CORBA
 378      * system exception will be thrown.
 379      */
 380     void run ();
 381
 382     /**
 383      * Instructs the ORB to initialize itself and run its event loop in
 384      * the current thread, not returning until the ORB has shut down or
 385      * the time value specified through @a tv has expired.  If an
 386      * error occurs during initialization or at runtime, a CORBA
 387      * system exception will be thrown.  @a tv is reduced by the
 388      * amount of time spent in this call.
 389      *
 390      * If this function is called with a @ tv value, client threads
 391      * making invocations will continue their operations. When the
 392      * operation times out and returns, any invocations showing up on
 393      * the server will be buffered by TCP.
 394      **/
 395     void run (ACE_Time_Value &tv);
 396
 397     /**
 398      * Instructs the ORB to initialize itself and run its event loop in
 399      * the current thread, not returning until the ORB has shut down or
 400      * the time value specified through @a tv has expired.  If an error
 401      * occurs during initialization or at runtime, a CORBA system
 402      * exception will be thrown.  @a tv is reduced by the amount of time
 403      * spent in this call.  If @a tv is 0, it means that the timeout
 404      * is infinite.  If @a tv is @c ACE_Time_Value::zero, it specifies
 405      * to poll and does not block.
 406      *
 407      * If this function is called with @a tv value, client threads
 408      * making invocations will continue their operations. When the
 409      * operation times out and returns, any invocations showing up on
 410      * the server will be buffered by TCP.
 411      **/
 412     void run (ACE_Time_Value *tv);
 413
 414     /// Returns an indication of whether the ORB needs to perform some
 415     /// work.
 416     CORBA::Boolean work_pending ();
 417
 418     /// Returns an indication of whether the ORB needs to perform some
 419     /// work but will look for work pending for no more than the
 420     /// specified time.
 421     /**
 422      * @note This is useful for implementing an event loop with an
 423      *       idle timeout.
 424      */
 425     CORBA::Boolean work_pending (ACE_Time_Value &tv);
 426
 427     /**
 428      * This operation performs an implementation-defined unit of work.
 429      * Note that the default behavior is to block if the unit of work
 430      * is not present; this behavior can be modified by passing an
 431      * appropriate @c ACE_Time_Value as described in run().
 432      **/
 433     void perform_work ();
 434     void perform_work (ACE_Time_Value &tv);
 435     void perform_work (ACE_Time_Value *tv);
 436
 437     /**
 438      * This operation instructs the ORB to shut down. Shutting down the
 439      * ORB causes all Object Adapters to be shut down. If
 440      * @c wait_for_completion parameter is TRUE, this operation blocks
 441      * until all ORB processing (including request processing and object
 442      * deactivation or other operations associated with object adapters)
 443      * has completed.
 444      */
 445     void shutdown (CORBA::Boolean wait_for_completion = false);
 446
 447     /**
 448      * Explicitly destroy the ORB, releasing any resources.  Note that
 449      * TAO *cannot* implicitly release the resources even if you have
 450      * destroyed all the references to a particular ORB since
 451      * CORBA::ORB_init() is required to return the same pointer if
 452      * called with the same ORBid, only after ORB::destroy() is called
 453      * it may return a new one.
 454      *
 455      * The results of multi-threaded applications, trying to destroy ()
 456      * the ORB in one thread and trying to service a request in another
 457      * thread are not well defined. TAO does not support such cases.
 458      */
 459     void destroy ();
 460
 461     /**
 462      * This method acts as a mini-bootstrapping Naming Service, which is
 463      * provided by the ORB for certain well-known object references.  TAO
 464      * supports the "NameService", "TradingService", "RootPOA",
 465      * "ImplRepo", and "POACurrent" via this method.  The @c timeout
 466      * value bounds the amount of time the ORB blocks waiting to
 467      * resolve the service.  This is most useful for bootstrapping
 468      * remote services, such as the "NameService" or "TradingService",
 469      * that are commonly resolved via multicast.  By default, the
 470      * value is 0, which means "use the @c
 471      * TAO_DEFAULT_SERVICE_RESOLUTION_TIMEOUT timeout period".
 472      *
 473      * @note By using a default value for the @c timeout parameter,
 474      *       TAO will remains compliant with the CORBA
 475      *       resolve_initial_references() specification.
 476      */
 477     CORBA::Object_ptr resolve_initial_references (
 478       const char *name,
 479       ACE_Time_Value *timeout = 0);
 480
 481 #if !defined(CORBA_E_MICRO)
 482     /// Register an object reference with the ORB.
 483     void register_initial_reference (const char * id, CORBA::Object_ptr obj);
 484
 485     /// Unregister an object reference with the ORB.
 486     CORBA::Object_ptr unregister_initial_reference (const char * id);
 487 #endif
 488
 489     /// Returns a sequence of ObjectIds that lists which objects have
 490     /// references available via the initial references mechanism.
 491     CORBA::ORB::ObjectIdList_ptr list_initial_services ();
 492
 493 #if !defined(CORBA_E_MICRO)
 494     CORBA::Policy_ptr create_policy (CORBA::PolicyType type,
 495                                      const CORBA::Any& val);
 496 #endif
 497
 498     // ----------------------------------------------------------------
 499     // = TAO-specific extensions to the CORBA specification.
 500     // ----------------------------------------------------------------
 501
 502 #if !defined(CORBA_E_MICRO)
 503     /// Create an empty policy, usually to be filled in later by
 504     /// demarshaling.
 505     CORBA::Policy_ptr _create_policy (CORBA::PolicyType type);
 506 #endif
 507
 508     /// Reference counting...
 509     unsigned long _incr_refcount ();
 510     unsigned long _decr_refcount ();
 511     unsigned long _refcount () const;
 512
 513     /// Set the IOR flag.
 514     void _use_omg_ior_format (CORBA::Boolean ior);
 515
 516     /// Get the IOR flag.
 517     CORBA::Boolean _use_omg_ior_format ();
 518
 519     /// Get the ORB core.
 520     TAO_ORB_Core *orb_core () const;
 521
 522     /// Factory method that creates an ORB.
 523     static CORBA::ORB_ptr _tao_make_ORB (TAO_ORB_Core * orb_core);
 524
 525     // Useful for template programming.
 526     typedef ORB_ptr _ptr_type;
 527     typedef ORB_var _var_type;
 528     typedef ORB_out _out_type;
 529
 530     /// Get the Timeout value
 531     ACE_Time_Value *get_timeout ();
 532
 533   protected:
 534     // We must be created via the @c CORBA::ORB_init() function.
 535     ORB (TAO_ORB_Core *orb_core);
 536
 537     /// Destructor
 538     /**
 539      * Protected destructor to enforce proper memory management
 540      * through the reference counting mechanism.
 541      */
 542     ~ORB ();
 543
 544     /// Resolve the Policy Manager for this ORB.
 545     CORBA::Object_ptr resolve_policy_manager ();
 546
 547     /// Resolve the Policy Current for this thread.
 548     CORBA::Object_ptr resolve_policy_current ();
 549
 550   private:
 551     /// Resolve the given service based on the service ID.
 552     /**
 553      * "@c resolve_service" is a legacy name.  This method now simply
 554      * sets up a default initial reference that will be subsequently
 555      * used in resolve_initial_references().
 556      */
 557     void resolve_service (TAO::MCAST_SERVICEID service_id);
 558
 559     /// Convert an OMG IOR into an object reference.
 560     CORBA::Object_ptr ior_string_to_object (const char* ior);
 561
 562     /// Convert an URL style IOR into an object reference.
 563     CORBA::Object_ptr url_ior_string_to_object (const char* ior);
 564
 565     /// Check if ORB has shutdown.  If it has, throw the appropriate
 566     /// exception.
 567     void check_shutdown ();
 568
 569     /// Set the timeout value
 570     void set_timeout (ACE_Time_Value * timeout);
 571
 572   private:
 573     /// Maintains a reference count of number of instantiations of the
 574     /// ORB.
 575     std::atomic<uint32_t> refcount_;
 576
 577     /// The ORB_Core that created us....
 578     TAO_ORB_Core * orb_core_;
 579
 580     /// Decides whether to use the URL notation or to use IOR notation.
 581     CORBA::Boolean use_omg_ior_format_;
 582
 583     // Prevent copying and assignment.
 584     ORB (const ORB &);
 585     ORB &operator= (const ORB &);
 586
 587     /// Timeout value
 588     ACE_Time_Value * timeout_;
 589   };
 590 }  // End namespace CORBA
 591
 592 TAO_END_VERSIONED_NAMESPACE_DECL
 593
 594 #if defined (__ACE_INLINE__)
 595 # include "tao/ORB.inl"
 596 #endif /* __ACE_INLINE__ */
 597
 598 #include /**/ "ace/post.h"
 599
 600 #endif /* TAO_ORB_H */