Disambiguate smart pointer type aliases (#583).

CONTRIBUTING.md

@@ -29,6 +29,14 @@ We welcome contributions from the community. Here are some guidelines.
 * Global static non-pod variables are allowed because Envoy correctly joins all threads on exit.
   However, care is needed during init and static accessor functions may be required.
 * OOM events (both memory and FDs) are considered fatal crashing errors.
+* Use your GitHub name in TODO comments, e.g. `TODO(foobar): blah`.
+* Smart pointers are type aliased:
+  * `typedef std::unique_ptr<Foo> FooPtr;`
+  * `typedef std::shared_ptr<Bar> BarSharedPtr;`
+  * `typedef std::shareD_ptr<const Blah> BlahConstSharedPtr;`
+  * Regular pointers (e.g. `int* foo`) should not be type aliased.
+* API-level comments should follow normal Doxygen conventions. Use `@param` to describe
+  parameters, `@return <return-type>` for return values.
 * There are probably a few other things missing from this list. We will add them as they
   are brought to our attention.
 

include/envoy/access_log/access_log.h

@@ -19,7 +19,7 @@ class AccessLogManager {
    * @param file_name specifies the file to create/open.
    * @return the opened file.
    */
-  virtual Filesystem::FilePtr createAccessLog(const std::string& file_name) PURE;
+  virtual Filesystem::FileSharedPtr createAccessLog(const std::string& file_name) PURE;
 };
 
 typedef std::unique_ptr<AccessLogManager> AccessLogManagerPtr;

include/envoy/api/api.h

@@ -25,9 +25,10 @@ class Api {
    * @param dispatcher supplies the dispatcher uses for async flushing.
    * @param lock supplies the lock to use for cross thread appends.
    */
-  virtual Filesystem::FilePtr createFile(const std::string& path, Event::Dispatcher& dispatcher,
-                                         Thread::BasicLockable& lock,
-                                         Stats::Store& stats_store) PURE;
+  virtual Filesystem::FileSharedPtr createFile(const std::string& path,
+                                               Event::Dispatcher& dispatcher,
+                                               Thread::BasicLockable& lock,
+                                               Stats::Store& stats_store) PURE;
 
   /**
    * @return bool whether a file exists and can be opened for read on disk.

include/envoy/event/dispatcher.h

@@ -37,7 +37,7 @@ class Dispatcher {
    * @return Network::ClientConnectionPtr a client connection that is owned by the caller.
    */
   virtual Network::ClientConnectionPtr
-  createClientConnection(Network::Address::InstancePtr address) PURE;
+  createClientConnection(Network::Address::InstanceConstSharedPtr address) PURE;
 
   /**
    * Create an SSL client connection.
@@ -47,7 +47,7 @@ class Dispatcher {
    */
   virtual Network::ClientConnectionPtr
   createSslClientConnection(Ssl::ClientContext& ssl_ctx,
-                            Network::Address::InstancePtr address) PURE;
+                            Network::Address::InstanceConstSharedPtr address) PURE;
 
   /**
    * Create an async DNS resolver. Only a single resolver can exist in the process at a time and it

include/envoy/filesystem/filesystem.h

@@ -47,7 +47,7 @@ class File {
   virtual void reopen() PURE;
 };
 
-typedef std::shared_ptr<File> FilePtr;
+typedef std::shared_ptr<File> FileSharedPtr;
 
 /**
  * Abstraction for a file watcher.

include/envoy/http/access_log.h

@@ -52,7 +52,7 @@ class RequestInfo {
   /**
    * Filter can trigger this callback when an upstream host has been selected.
    */
-  virtual void onUpstreamHostSelected(Upstream::HostDescriptionPtr host) PURE;
+  virtual void onUpstreamHostSelected(Upstream::HostDescriptionConstSharedPtr host) PURE;
 
   /**
    * @return the time that the first byte of the request was received.
@@ -97,7 +97,7 @@ class RequestInfo {
   /**
    * @return upstream host description.
    */
-  virtual Upstream::HostDescriptionPtr upstreamHost() const PURE;
+  virtual Upstream::HostDescriptionConstSharedPtr upstreamHost() const PURE;
 
   /**
    * @return whether the request is a health check request or not.
@@ -144,7 +144,7 @@ class Instance {
                    const RequestInfo& request_info) PURE;
 };
 
-typedef std::shared_ptr<Instance> InstancePtr;
+typedef std::shared_ptr<Instance> InstanceSharedPtr;
 
 /**
  * Interface for access log formatter.

include/envoy/http/conn_pool.h

@@ -45,15 +45,17 @@ class Callbacks {
    * @param host supplies the description of the host that caused the failure. This may be nullptr
    *             if no host was involved in the failure (for example overflow).
    */
-  virtual void onPoolFailure(PoolFailureReason reason, Upstream::HostDescriptionPtr host) PURE;
+  virtual void onPoolFailure(PoolFailureReason reason,
+                             Upstream::HostDescriptionConstSharedPtr host) PURE;
 
   /**
    * Called when a connection is available to process a request/response.
    * @param encoder supplies the request encoder to use.
    * @param host supplies the description of the host that will carry the request. For logical
    *             connection pools the description may be different each time this is called.
    */
-  virtual void onPoolReady(Http::StreamEncoder& encoder, Upstream::HostDescriptionPtr host) PURE;
+  virtual void onPoolReady(Http::StreamEncoder& encoder,
+                           Upstream::HostDescriptionConstSharedPtr host) PURE;
 };
 
 /**

include/envoy/http/filter.h

@@ -99,7 +99,7 @@ class StreamFilterCallbacks {
    *       knows that it has modified the headers in a way that would affect routing. In the future
    *       we may also want to allow the filter to override the route entry.
    */
-  virtual Router::RoutePtr route() PURE;
+  virtual Router::RouteConstSharedPtr route() PURE;
 
   /**
    * @return uint64_t the ID of the originating stream for logging purposes.
@@ -202,7 +202,7 @@ class StreamDecoderFilter {
   virtual void setDecoderFilterCallbacks(StreamDecoderFilterCallbacks& callbacks) PURE;
 };
 
-typedef std::shared_ptr<StreamDecoderFilter> StreamDecoderFilterPtr;
+typedef std::shared_ptr<StreamDecoderFilter> StreamDecoderFilterSharedPtr;
 
 /**
  * Stream encoder filter callbacks add additional callbacks that allow a encoding filter to restart
@@ -264,14 +264,14 @@ class StreamEncoderFilter {
   virtual void setEncoderFilterCallbacks(StreamEncoderFilterCallbacks& callbacks) PURE;
 };
 
-typedef std::shared_ptr<StreamEncoderFilter> StreamEncoderFilterPtr;
+typedef std::shared_ptr<StreamEncoderFilter> StreamEncoderFilterSharedPtr;
 
 /**
  * A filter that handles both encoding and decoding.
  */
 class StreamFilter : public StreamDecoderFilter, public StreamEncoderFilter {};
 
-typedef std::shared_ptr<StreamFilter> StreamFilterPtr;
+typedef std::shared_ptr<StreamFilter> StreamFilterSharedPtr;
 
 /**
  * These callbacks are provided by the connection manager to the factory so that the factory can
@@ -285,25 +285,25 @@ class FilterChainFactoryCallbacks {
    * Add a decoder filter that is used when reading stream data.
    * @param filter supplies the filter to add.
    */
-  virtual void addStreamDecoderFilter(Http::StreamDecoderFilterPtr filter) PURE;
+  virtual void addStreamDecoderFilter(Http::StreamDecoderFilterSharedPtr filter) PURE;
 
   /**
    * Add an encoder filter that is used when writing stream data.
    * @param filter supplies the filter to add.
    */
-  virtual void addStreamEncoderFilter(Http::StreamEncoderFilterPtr filter) PURE;
+  virtual void addStreamEncoderFilter(Http::StreamEncoderFilterSharedPtr filter) PURE;
 
   /**
    * Add a decoder/encoder filter that is used both when reading and writing stream data.
    * @param filter supplies the filter to add.
    */
-  virtual void addStreamFilter(Http::StreamFilterPtr filter) PURE;
+  virtual void addStreamFilter(Http::StreamFilterSharedPtr filter) PURE;
 
   /**
    * Add an access log handler that is called when the stream is destroyed.
    * @param handler supplies the handler to add.
    */
-  virtual void addAccessLogHandler(Http::AccessLog::InstancePtr handler) PURE;
+  virtual void addAccessLogHandler(Http::AccessLog::InstanceSharedPtr handler) PURE;
 };
 
 /**

include/envoy/local_info/local_info.h

@@ -15,7 +15,7 @@ class LocalInfo {
   /**
    * @return the local (non-loopback) address of the server.
    */
-  virtual Network::Address::InstancePtr address() const PURE;
+  virtual Network::Address::InstanceConstSharedPtr address() const PURE;
 
   /**
    * Human readable zone name. E.g., "us-east-1a".

include/envoy/mongo/bson.h

@@ -9,7 +9,7 @@
 namespace Bson {
 
 class Document;
-typedef std::shared_ptr<Document> DocumentPtr;
+typedef std::shared_ptr<Document> DocumentSharedPtr;
 
 /**
  * A BSON document field. This is essentially a variably typed parameter that can be "cast" to
@@ -85,19 +85,19 @@ class Document {
 public:
   virtual ~Document() {}
 
-  virtual DocumentPtr addDouble(const std::string& key, double value) PURE;
-  virtual DocumentPtr addString(const std::string& key, std::string&& value) PURE;
-  virtual DocumentPtr addDocument(const std::string& key, DocumentPtr value) PURE;
-  virtual DocumentPtr addArray(const std::string& key, DocumentPtr value) PURE;
-  virtual DocumentPtr addBinary(const std::string& key, std::string&& value) PURE;
-  virtual DocumentPtr addObjectId(const std::string& key, Field::ObjectId&& value) PURE;
-  virtual DocumentPtr addBoolean(const std::string& key, bool value) PURE;
-  virtual DocumentPtr addDatetime(const std::string& key, int64_t value) PURE;
-  virtual DocumentPtr addNull(const std::string& key) PURE;
-  virtual DocumentPtr addRegex(const std::string& key, Field::Regex&& value) PURE;
-  virtual DocumentPtr addInt32(const std::string& key, int32_t value) PURE;
-  virtual DocumentPtr addTimestamp(const std::string& key, int64_t value) PURE;
-  virtual DocumentPtr addInt64(const std::string& key, int64_t value) PURE;
+  virtual DocumentSharedPtr addDouble(const std::string& key, double value) PURE;
+  virtual DocumentSharedPtr addString(const std::string& key, std::string&& value) PURE;
+  virtual DocumentSharedPtr addDocument(const std::string& key, DocumentSharedPtr value) PURE;
+  virtual DocumentSharedPtr addArray(const std::string& key, DocumentSharedPtr value) PURE;
+  virtual DocumentSharedPtr addBinary(const std::string& key, std::string&& value) PURE;
+  virtual DocumentSharedPtr addObjectId(const std::string& key, Field::ObjectId&& value) PURE;
+  virtual DocumentSharedPtr addBoolean(const std::string& key, bool value) PURE;
+  virtual DocumentSharedPtr addDatetime(const std::string& key, int64_t value) PURE;
+  virtual DocumentSharedPtr addNull(const std::string& key) PURE;
+  virtual DocumentSharedPtr addRegex(const std::string& key, Field::Regex&& value) PURE;
+  virtual DocumentSharedPtr addInt32(const std::string& key, int32_t value) PURE;
+  virtual DocumentSharedPtr addTimestamp(const std::string& key, int64_t value) PURE;
+  virtual DocumentSharedPtr addInt64(const std::string& key, int64_t value) PURE;
 
   virtual bool operator==(const Document& rhs) const PURE;
   virtual int32_t byteSize() const PURE;

include/envoy/mongo/codec.h

@@ -58,8 +58,8 @@ class InsertMessage : public virtual Message {
   virtual void flags(int32_t flags) PURE;
   virtual const std::string& fullCollectionName() const PURE;
   virtual void fullCollectionName(const std::string& name) PURE;
-  virtual const std::list<Bson::DocumentPtr>& documents() const PURE;
-  virtual std::list<Bson::DocumentPtr>& documents() PURE;
+  virtual const std::list<Bson::DocumentSharedPtr>& documents() const PURE;
+  virtual std::list<Bson::DocumentSharedPtr>& documents() PURE;
 };
 
 typedef std::unique_ptr<InsertMessage> InsertMessagePtr;
@@ -104,9 +104,9 @@ class QueryMessage : public virtual Message {
   virtual int32_t numberToReturn() const PURE;
   virtual void numberToReturn(int32_t to_return) PURE;
   virtual const Bson::Document* query() const PURE;
-  virtual void query(Bson::DocumentPtr&& query) PURE;
+  virtual void query(Bson::DocumentSharedPtr&& query) PURE;
   virtual const Bson::Document* returnFieldsSelector() const PURE;
-  virtual void returnFieldsSelector(Bson::DocumentPtr&& fields) PURE;
+  virtual void returnFieldsSelector(Bson::DocumentSharedPtr&& fields) PURE;
 };
 
 typedef std::unique_ptr<QueryMessage> QueryMessagePtr;
@@ -133,8 +133,8 @@ class ReplyMessage : public virtual Message {
   virtual void startingFrom(int32_t starting_from) PURE;
   virtual int32_t numberReturned() const PURE;
   virtual void numberReturned(int32_t number_returned) PURE;
-  virtual const std::list<Bson::DocumentPtr>& documents() const PURE;
-  virtual std::list<Bson::DocumentPtr>& documents() PURE;
+  virtual const std::list<Bson::DocumentSharedPtr>& documents() const PURE;
+  virtual std::list<Bson::DocumentSharedPtr>& documents() PURE;
 };
 
 typedef std::unique_ptr<ReplyMessage> ReplyMessagePtr;

include/envoy/network/address.h

@@ -128,7 +128,7 @@ class Instance {
   virtual Type type() const PURE;
 };
 
-typedef std::shared_ptr<const Instance> InstancePtr;
+typedef std::shared_ptr<const Instance> InstanceConstSharedPtr;
 
 } // Address
 } // Network

include/envoy/network/dns.h

@@ -30,7 +30,7 @@ class DnsResolver {
    * @param address_list supplies the list of resolved IP addresses. The list will be empty if
    *                     the resolution failed.
    */
-  typedef std::function<void(std::list<Address::InstancePtr>&& address_list)> ResolveCb;
+  typedef std::function<void(std::list<Address::InstanceConstSharedPtr>&& address_list)> ResolveCb;
 
   /**
    * Initiate an async DNS resolution.

include/envoy/network/filter.h

@@ -32,7 +32,7 @@ class WriteFilter {
   virtual FilterStatus onWrite(Buffer::Instance& data) PURE;
 };
 
-typedef std::shared_ptr<WriteFilter> WriteFilterPtr;
+typedef std::shared_ptr<WriteFilter> WriteFilterSharedPtr;
 
 /**
  * Callbacks used by individual read filter instances to communicate with the filter manager.
@@ -58,12 +58,12 @@ class ReadFilterCallbacks {
    * between multiple network level filters, for example the TCP proxy filter communicating its
    * selection to another filter for logging.
    */
-  virtual Upstream::HostDescriptionPtr upstreamHost() PURE;
+  virtual Upstream::HostDescriptionConstSharedPtr upstreamHost() PURE;
 
   /**
    * Set the currently selected upstream host for the connection.
    */
-  virtual void upstreamHost(Upstream::HostDescriptionPtr host) PURE;
+  virtual void upstreamHost(Upstream::HostDescriptionConstSharedPtr host) PURE;
 };
 
 /**
@@ -102,14 +102,14 @@ class ReadFilter {
   virtual void initializeReadFilterCallbacks(ReadFilterCallbacks& callbacks) PURE;
 };
 
-typedef std::shared_ptr<ReadFilter> ReadFilterPtr;
+typedef std::shared_ptr<ReadFilter> ReadFilterSharedPtr;
 
 /**
  * A combination read and write filter. This allows a single filter instance to cover
  * both the read and write paths.
  */
 class Filter : public WriteFilter, public ReadFilter {};
-typedef std::shared_ptr<Filter> FilterPtr;
+typedef std::shared_ptr<Filter> FilterSharedPtr;
 
 /**
  * Interface for adding individual network filters to a manager.
@@ -122,19 +122,19 @@ class FilterManager {
    * Add a write filter to the connection. Filters are invoked in LIFO order (the last added
    * filter is called first).
    */
-  virtual void addWriteFilter(WriteFilterPtr filter) PURE;
+  virtual void addWriteFilter(WriteFilterSharedPtr filter) PURE;
 
   /**
    * Add a combination filter to the connection. Equivalent to calling both addWriteFilter()
    * and addReadFilter() with the same filter instance.
    */
-  virtual void addFilter(FilterPtr filter) PURE;
+  virtual void addFilter(FilterSharedPtr filter) PURE;
 
   /**
    * Add a read filter to the connection. Filters are invoked in FIFO order (the filter added
    * first is called first).
    */
-  virtual void addReadFilter(ReadFilterPtr filter) PURE;
+  virtual void addReadFilter(ReadFilterSharedPtr filter) PURE;
 
   /**
    * Initialize all of the installed read filters. This effectively calls onNewConnection() on

include/envoy/network/listen_socket.h

@@ -15,7 +15,7 @@ class ListenSocket {
   /**
    * @return the address that the socket is listening on.
    */
-  virtual Address::InstancePtr localAddress() PURE;
+  virtual Address::InstanceConstSharedPtr localAddress() PURE;
 
   /**
    * @return fd the listen socket's file descriptor.

include/envoy/redis/conn_pool.h

@@ -77,7 +77,7 @@ class ClientFactory {
   /**
    * Create a client given an upstream host.
    */
-  virtual ClientPtr create(Upstream::ConstHostPtr host, Event::Dispatcher& dispatcher) PURE;
+  virtual ClientPtr create(Upstream::HostConstSharedPtr host, Event::Dispatcher& dispatcher) PURE;
 };
 
 /**

include/envoy/router/rds.h

@@ -12,11 +12,12 @@ class RouteConfigProvider {
   virtual ~RouteConfigProvider() {}
 
   /**
-   * @return Router::ConfigPtr a route configuration for use during a single request. The returned
+   * @return Router::ConfigConstSharedPtr a route configuration for use during a single request. The
+   * returned
    *         config may be different on a subsequent call, so a new config should be acquired for
    *         each request flow.
    */
-  virtual Router::ConfigPtr config() PURE;
+  virtual Router::ConfigConstSharedPtr config() PURE;
 };
 
 typedef std::unique_ptr<RouteConfigProvider> RouteConfigProviderPtr;