cleanup: clarify Cluster.filters and Dispatcher::createClientConnection

api/envoy/api/v2/cds.proto

@@ -641,9 +641,9 @@ message Cluster {
  // checking before removing it from the cluster.
  bool drain_connections_on_host_removal = 32;
 
- // An optional list of network filters that make up the filter chain for
- // outgoing connections made by the cluster. Order matters as the filters are
- // processed sequentially as connection events happen.
+ // An (optional) network filter chain, listed in the order the filters should be applied.
+ // The chain will be applied to all outgoing connections that Envoy makes to the upstream
+ // servers of this cluster.
  repeated cluster.Filter filters = 40;
 
  // [#not-implemented-hide:] New mechanism for LB policy configuration. Used only if the

api/envoy/api/v3alpha/cds.proto

@@ -634,9 +634,9 @@ message Cluster {
  // checking before removing it from the cluster.
  bool drain_connections_on_host_removal = 32;
 
- // An optional list of network filters that make up the filter chain for
- // outgoing connections made by the cluster. Order matters as the filters are
- // processed sequentially as connection events happen.
+ // An (optional) network filter chain, listed in the order the filters should be applied.
+ // The chain will be applied to all outgoing connections that Envoy makes to the upstream
+ // servers of this cluster.
  repeated cluster.Filter filters = 40;
 }
 

include/envoy/event/dispatcher.h

@@ -59,7 +59,7 @@ class Dispatcher {
  virtual TimeSource& timeSource() PURE;
 
  /**
- * Initialize stats for this dispatcher. Note that this can't generally be done at construction
+ * Initializes stats for this dispatcher. Note that this can't generally be done at construction
  * time, since the main and worker thread dispatchers are constructed before
  * ThreadLocalStoreImpl::initializeThreading.
  * @param scope the scope to contain the new per-dispatcher stats created here.
@@ -68,12 +68,12 @@ class Dispatcher {
  virtual void initializeStats(Stats::Scope& scope, const std::string& prefix) PURE;
 
  /**
- * Clear any items in the deferred deletion queue.
+ * Clears any items in the deferred deletion queue.
  */
  virtual void clearDeferredDeleteList() PURE;
 
  /**
- * Create a server connection.
+ * Wraps an already-accepted socket in an instance of Envoy's server Network::Connection.
  * @param socket supplies an open file descriptor and connection metadata to use for the
  * connection. Takes ownership of the socket.
  * @param transport_socket supplies a transport socket to be used by the connection.
@@ -84,7 +84,8 @@ class Dispatcher {
  Network::TransportSocketPtr&& transport_socket) PURE;
 
  /**
- * Create a client connection.
+ * Creates an instance of Envoy's Network::ClientConnection. Does NOT initiate the connection;
+ * the caller must then call connect() on the returned Network::ClientConnection.
  * @param address supplies the address to connect to.
  * @param source_address supplies an address to bind to or nullptr if no bind is necessary.
  * @param transport_socket supplies a transport socket to be used by the connection.
@@ -99,7 +100,7 @@ class Dispatcher {
  const Network::ConnectionSocket::OptionsSharedPtr& options) PURE;
 
  /**
- * Create an async DNS resolver. The resolver should only be used on the thread that runs this
+ * Creates an async DNS resolver. The resolver should only be used on the thread that runs this
  * dispatcher.
  * @param resolvers supplies the addresses of DNS resolvers that this resolver should use. If left
  * empty, it will not use any specific resolvers, but use defaults (/etc/resolv.conf)
@@ -109,7 +110,7 @@ class Dispatcher {
  createDnsResolver(const std::vector<Network::Address::InstanceConstSharedPtr>& resolvers) PURE;
 
  /**
- * Create a file event that will signal when a file is readable or writable. On UNIX systems this
+ * Creates a file event that will signal when a file is readable or writable. On UNIX systems this
  * can be used for any file like interface (files, sockets, etc.).
  * @param fd supplies the fd to watch.
  * @param cb supplies the callback to fire when the file is ready.
@@ -126,7 +127,7 @@ class Dispatcher {
  virtual Filesystem::WatcherPtr createFilesystemWatcher() PURE;
 
  /**
- * Create a listener on a specific port.
+ * Creates a listener on a specific port.
  * @param socket supplies the socket to listen on.
  * @param cb supplies the callbacks to invoke for listener events.
  * @param bind_to_port controls whether the listener binds to a transport port or not.
@@ -139,31 +140,31 @@ class Dispatcher {
  bool hand_off_restored_destination_connections) PURE;
 
  /**
- * Create a logical udp listener on a specific port.
+ * Creates a logical udp listener on a specific port.
  * @param socket supplies the socket to listen on.
  * @param cb supplies the udp listener callbacks to invoke for listener events.
  * @return Network::ListenerPtr a new listener that is owned by the caller.
  */
  virtual Network::ListenerPtr createUdpListener(Network::Socket& socket,
  Network::UdpListenerCallbacks& cb) PURE;
  /**
- * Allocate a timer. @see Timer for docs on how to use the timer.
+ * Allocates a timer. @see Timer for docs on how to use the timer.
  * @param cb supplies the callback to invoke when the timer fires.
  */
  virtual Event::TimerPtr createTimer(TimerCb cb) PURE;
 
  /**
- * Submit an item for deferred delete. @see DeferredDeletable.
+ * Submits an item for deferred delete. @see DeferredDeletable.
  */
  virtual void deferredDelete(DeferredDeletablePtr&& to_delete) PURE;
 
  /**
- * Exit the event loop.
+ * Exits the event loop.
  */
  virtual void exit() PURE;
 
  /**
- * Listen for a signal event. Only a single dispatcher in the process can listen for signals.
+ * Listens for a signal event. Only a single dispatcher in the process can listen for signals.
  * If more than one dispatcher calls this routine in the process the behavior is undefined.
  *
  * @param signal_num supplies the signal to listen on.
@@ -173,13 +174,13 @@ class Dispatcher {
  virtual SignalEventPtr listenForSignal(int signal_num, SignalCb cb) PURE;
 
  /**
- * Post a functor to the dispatcher. This is safe cross thread. The functor runs in the context
+ * Posts a functor to the dispatcher. This is safe cross thread. The functor runs in the context
  * of the dispatcher event loop which may be on a different thread than the caller.
  */
  virtual void post(PostCb callback) PURE;
 
  /**
- * Run the event loop. This will not return until exit() is called either from within a callback
+ * Runs the event loop. This will not return until exit() is called either from within a callback
  * or from a different thread.
  * @param type specifies whether to run in blocking mode (run() will not return until exit() is
  * called) or non-blocking mode where only active events will be executed and then