1# Topology Package Design
2
3This document outlines the design for this package.
4
5## Topology
6
7The `Topology` type handles monitoring the state of a MongoDB deployment and selecting servers.
8Updating the description is handled by finite state machine which implements the server discovery
9and monitoring specification. A `Topology` can be connected and fully disconnected, which enables
10saving resources. The `Topology` type also handles server selection following the server selection
11specification.
12
13## Server
14
15The `Server` type handles heartbeating a MongoDB server and holds a pool of connections.
16
17## Connection
18
19Connections are handled by two main types and an auxiliary type. The two main types are `connection`
20and `Connection`. The first holds most of the logic required to actually read and write wire
21messages. Instances can be created with the `newConnection` method. Inside the `newConnection`
22method the auxiliary type, `initConnection` is used to perform the connection handshake. This is
23required because the `connection` type does not fully implement `driver.Connection` which is
24required during handshaking. The `Connection` type is what is actually returned to a consumer of the
25`topology` package. This type does implement the `driver.Connection` type, holds a reference to a
26`connection` instance, and exists mainly to prevent accidental continued usage of a connection after
27closing it.
28
29The connection implementations in this package are conduits for wire messages but they have no
30ability to encode, decode, or validate wire messages. That must be handled by consumers.
31
32## Pool
33
34The `pool` type implements a connection pool. It handles caching idle connections and dialing
35new ones, but it does not track a maximum number of connections. That is the responsibility of a
36wrapping type, like `Server`.
37
38The `pool` type has no concept of closing, instead it has concepts of connecting and disconnecting.
39This allows a `Topology` to be disconnected,but keeping the memory around to be reconnected later.
40There is a `close` method, but this is used to close a connection.
41
42There are three methods related to getting and putting connections: `get`, `close`, and `put`. The
43`get` method will either retrieve a connection from the cache or it will dial a new `connection`.
44The `close` method will close the underlying socket of a `connection`. The `put` method will put a
45connection into the pool, placing it in the cache if there is space, otherwise it will close it.
View as plain text