diff --git a/api/envoy/api/v2/cds.proto b/api/envoy/api/v2/cds.proto index b2b71384f8c8..85e9a3827c3c 100644 --- a/api/envoy/api/v2/cds.proto +++ b/api/envoy/api/v2/cds.proto @@ -647,9 +647,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 diff --git a/api/envoy/api/v3alpha/cds.proto b/api/envoy/api/v3alpha/cds.proto index c1c18b110be0..506224a7ba46 100644 --- a/api/envoy/api/v3alpha/cds.proto +++ b/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; } diff --git a/include/envoy/event/dispatcher.h b/include/envoy/event/dispatcher.h index 8c3a8b8a88b7..b9ae70960df2 100644 --- a/include/envoy/event/dispatcher.h +++ b/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& 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,7 +140,7 @@ 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. @@ -147,23 +148,23 @@ class Dispatcher { 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