TAO/tao/Endpoint.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file   Endpoint.h
   6  *
   7  * Endpoint interface, part of TAO pluggable protocol framework.
   8  *
   9  *  @author Marina Spivak <marina@cs.wustl.edu>
  10  */
  11 //=============================================================================
  12
  13 #ifndef TAO_ENDPOINT_H
  14 #define TAO_ENDPOINT_H
  15
  16 #include /**/ "ace/pre.h"
  17 #include "ace/Thread_Mutex.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include /**/ "tao/TAO_Export.h"
  24 #include "tao/Basic_Types.h"
  25 #include "tao/orbconf.h"
  26
  27 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  28
  29 class TAO_ORB_Core;
  30
  31 /**
  32  * @class TAO_Endpoint
  33  *
  34  * @brief Defines the Endpoint interface in the Pluggable Protocol
  35  * framework.
  36  *
  37  * Lightweight encapsulation of addressing information for a
  38  * single acceptor endpoint.  In other words, Endpoint represents
  39  * a single point of contact for the server, and is the smallest
  40  * unit of addressing information necessary for a client to connect
  41  * to a server.
  42  * A Profile contains one or more Endpoints, i.e., knows of
  43  * one or more ways to contact server(s).
  44  */
  45 class TAO_Export TAO_Endpoint
  46 {
  47 public:
  48   /// Constructor.
  49   TAO_Endpoint (CORBA::ULong tag,
  50                 CORBA::Short priority = TAO_INVALID_PRIORITY);
  51
  52   /// Destructor.
  53   virtual ~TAO_Endpoint () = default;
  54
  55   /// IOP protocol tag accessor.
  56   CORBA::ULong tag () const;
  57
  58   /// @c priority_ attribute setter.
  59   void priority (CORBA::Short priority);
  60
  61   /// @c priority_ attribute getter.
  62   CORBA::Short priority () const;
  63
  64   /**
  65    * @name TAO_Endpoint Template Methods
  66    *
  67    * Abstract methods to be implemented by concrete subclasses.
  68    */
  69   //@{
  70   /**
  71    * @return true if this endpoint is equivalent to @a other_endpoint.
  72    */
  73   virtual CORBA::Boolean is_equivalent (const TAO_Endpoint *other_endpoint) = 0;
  74
  75   /// Endpoints can be linked in a list.
  76   /**
  77    * @return The next endpoint in the list, if any.
  78    */
  79   virtual TAO_Endpoint *next () = 0;
  80
  81   /**
  82    * Return the next endpoint in the list, but use protocol-specific
  83    * filtering to constrain the value. The orb core is needed to supply
  84    * any sort of filter arguments, and the root endpoint is needed in case
  85    * the algorithm needs to rewind. If the supplied root is 0, then this
  86    * is assumed to be the candidate next endpoint.
  87    *
  88    * To use this, the caller starts off the change with root == 0. This
  89    * is a bit of a violation in logic, a more correct implementation would
  90    * accept this == 0 and a non-null root.
  91    * To do iteration using next_filtered, do:
  92    *   for (TAO_Endpoint *ep = root_endpoint->next_filtered (orb_core, 0);
  93    *        ep != 0;
  94    *        ep = ep->next_filtered(orb_core, root_endpoint)) { }
  95    */
  96   virtual TAO_Endpoint *next_filtered (TAO_ORB_Core *, TAO_Endpoint *root);
  97
  98   /// Return a string representation for the address.
  99   /**
 100    * The purpose of this method is to provide a general interface to
 101    * the underlying address object's @c addr_to_string method.  This
 102    * allows the protocol implementor to select the appropriate string
 103    * format.
 104    *
 105    * @return -1 if buffer is too small.
 106    */
 107   virtual int addr_to_string (char *buffer, size_t length) = 0;
 108
 109   /// This method returns a deep copy of the corresponding endpoints by
 110   /// allocating memory.
 111   virtual TAO_Endpoint *duplicate () = 0;
 112
 113   /// Return a hash value for this object.
 114   virtual CORBA::ULong hash ()  = 0;
 115
 116 protected:
 117   /// Lock for the address lookup.
 118   /**
 119    * @todo This lock should be strategized so that we dont lock in
 120    *       single threaded configurations.  It is not possible to do
 121    *       this now as most of the information is available in the
 122    *       ORB_Core which is not available here.
 123    */
 124   mutable TAO_SYNCH_MUTEX addr_lookup_lock_;
 125
 126   /// Cache the hash value
 127   CORBA::ULong hash_val_ {};
 128
 129   /// IOP tag, identifying the protocol for which this endpoint
 130   /// contains addressing info.
 131   CORBA::ULong const tag_;
 132
 133   /**
 134    * CORBA priority of the acceptor this Endpoint is representing.
 135    * This is part of TAO 'prioritized endpoints' architecture, and is
 136    * currently used for RTCORBA only.
 137    */
 138   CORBA::Short priority_;
 139
 140 private:
 141   /// Endpoints should not be copied.
 142   TAO_Endpoint (const TAO_Endpoint&) = delete;
 143   void operator= (const TAO_Endpoint&) = delete;
 144 };
 145
 146 TAO_END_VERSIONED_NAMESPACE_DECL
 147
 148 #if defined (__ACE_INLINE__)
 149 # include "tao/Endpoint.inl"
 150 #endif /* __ACE_INLINE__ */
 151
 152 #include /**/ "ace/post.h"
 153 #endif  /* TAO_PROFILE_H */