Line data    Source code

       1             : #pragma once
       2             : 
       3             : #include "envoy/common/pure.h"
       4             : #include "envoy/event/deferred_deletable.h"
       5             : #include "envoy/upstream/upstream.h"
       6             : 
       7             : namespace Envoy {
       8             : namespace ConnectionPool {
       9             : 
      10             : /**
      11             :  * Controls the behavior of a canceled stream.
      12             :  */
      13             : enum class CancelPolicy {
      14             :   // By default, canceled streams allow a pending connection to complete and become
      15             :   // available for a future stream.
      16             :   Default,
      17             :   // When a stream is canceled, closes a pending connection if there will still be sufficient
      18             :   // connections to serve pending streams. CloseExcess is largely useful for callers that never
      19             :   // re-use connections (e.g. by closing rather than releasing connections). Using CloseExcess in
      20             :   // this situation guarantees that no idle connections will be held open by the conn pool awaiting
      21             :   // a connection stream.
      22             :   CloseExcess,
      23             : };
      24             : 
      25             : /**
      26             :  * Handle that allows a pending connection or stream to be canceled before it is completed.
      27             :  */
      28             : class Cancellable {
      29             : public:
      30         173 :   virtual ~Cancellable() = default;
      31             : 
      32             :   /**
      33             :    * Cancel the pending connection or stream.
      34             :    * @param cancel_policy a CancelPolicy that controls the behavior of this cancellation.
      35             :    */
      36             :   virtual void cancel(CancelPolicy cancel_policy) PURE;
      37             : };
      38             : 
      39             : /**
      40             :  * Controls the behavior when draining a connection pool.
      41             :  */
      42             : enum class DrainBehavior {
      43             :   // Starts draining a pool, by gracefully completing all requests and gracefully closing all
      44             :   // connections, in preparation for deletion. It is invalid to create new streams or
      45             :   // connections from this pool after draining a pool with this behavior.
      46             :   DrainAndDelete,
      47             :   // Actively drain all existing connection pool connections. This can be used in cases where
      48             :   // the connection pool is not being destroyed, but the caller wishes to make sure that
      49             :   // all new streams take place on a new connection. For example, when a health check failure
      50             :   // occurs.
      51             :   DrainExistingConnections,
      52             : };
      53             : 
      54             : /**
      55             :  * An instance of a generic connection pool.
      56             :  */
      57             : class Instance {
      58             : public:
      59         589 :   virtual ~Instance() = default;
      60             : 
      61             :   /**
      62             :    * Called when a connection pool has no pending streams, busy connections, or ready connections.
      63             :    */
      64             :   using IdleCb = std::function<void()>;
      65             : 
      66             :   /**
      67             :    * Register a callback that gets called when the connection pool is fully idle.
      68             :    */
      69             :   virtual void addIdleCallback(IdleCb cb) PURE;
      70             : 
      71             :   /**
      72             :    * Returns true if the pool does not have any connections or pending requests.
      73             :    */
      74             :   virtual bool isIdle() const PURE;
      75             : 
      76             :   /**
      77             :    * Drains the connections in a pool.
      78             :    * @param drain_behavior A DrainBehavior that controls the behavior of the draining.
      79             :    */
      80             :   virtual void drainConnections(DrainBehavior drain_behavior) PURE;
      81             : 
      82             :   /**
      83             :    * @return Upstream::HostDescriptionConstSharedPtr the host for which connections are pooled.
      84             :    */
      85             :   virtual Upstream::HostDescriptionConstSharedPtr host() const PURE;
      86             : 
      87             :   /**
      88             :    * Creates an upstream connection, if existing connections do not meet both current and
      89             :    * anticipated load.
      90             :    *
      91             :    * @return true if a connection was preconnected, false otherwise.
      92             :    */
      93             :   virtual bool maybePreconnect(float preconnect_ratio) PURE;
      94             : };
      95             : 
      96             : enum class PoolFailureReason {
      97             :   // A resource overflowed and policy prevented a new connection from being created.
      98             :   Overflow,
      99             :   // A local connection failure took place while creating a new connection.
     100             :   LocalConnectionFailure,
     101             :   // A remote connection failure took place while creating a new connection.
     102             :   RemoteConnectionFailure,
     103             :   // A timeout occurred while creating a new connection.
     104             :   Timeout,
     105             : };
     106             : 
     107             : } // namespace ConnectionPool
     108             : } // namespace Envoy