[/
    Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
   
    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]

[section:any_connection (Experimental) Type-erased connections with any_connection]
[nochunk]

[reflink any_connection] is a type-erased alternative to [reflink connection].
It's easier to use and features more functionality than plain `connection`.

[note
    This feature is experimental. Its API may change in subsequent releases.
]

When compared to [reflink connection], `any_connection`:

* Is type-erased. The type of the connection doesn't depend on the transport being used.
  Supported transports include plaintext TCP, TLS on top of TCP and UNIX domain sockets.
* Is easier to connect. For example, when using TCP, connection establishment methods will
  handle hostname resolution for you. This must be handled manually with `connection`.
* Can always be reconnected after closing it or after encountering an error.
  `connection` can't make this guarantee, especially when using TLS.
* Doesn't allow to customize the internal `Stream` type. Doing this
  allows supporting the point above.
* Doesn't support default completion tokens.
* Has equivalent performance.
* Other than session establishment, it has the same API as `connection`.

`any_connection` is expected to replace `connection` in the long run.



[heading Example]

To connect to a server using TCP, use the following:

[any_connection_tcp]

[refmem connect_params server_address] is an [reflink any_address], which is
a variant-like type that can hold a (hostname, port) pair or a UNIX socket path.
For example, to connect using a UNIX socket:

[any_connection_unix]



[heading Reconnection]

[reflink any_connection] can always be reconnected. [refmem any_connection connect]
and [refmem any_connection async_connect] will wipe any previous connection state.
This works even if an error or a timeout occurred, as opposed to `connection`.

For instance, the following can be used to implement retries for connection establishment:

[any_connection_reconnect]

Likewise, if you encounter a fatal error (like a network error), just call `connect` or `async_connect`.

If you need reliable, long-lived connections, consider [link mysql.connection_pool using a connection pool]
instead of rolling out your own strategy.





[heading TLS]

By default, [reflink any_connection] uses TLS when using TCP connections and the
server supports it. You can change this setting using [refmem connect_params ssl]:

[any_connection_ssl_mode]

See [link mysql.ssl.negotiation this section] for more info on MySQL TLS negotiation.

By default, `any_connection` will create an [asioreflink ssl__context ssl::context] object with suitable
default options for you, if required. If you want to configure TLS options beyond defaults,
you can pass your own context to `any_connection`'s constructor, and
it will be used:

[any_connection_ssl_ctx]


[endsect]