cluster

Documentation

Overview

Package cluster is not for public use.

The API for packages in the 'private' directory have no stability guarantee.

The packages within the 'private' directory would normally be put into an 'internal' directory to prohibit their use outside the 'mongo' directory. However, some MongoDB tools require very low-level access to the building blocks of a driver, so we have placed them under 'private' to allow these packages to be imported by projects that need them.

These package APIs may be modified in backwards-incompatible ways at any time.

You are strongly discouraged from directly using any packages under 'private'.

Index

• Variables
• func SelectServers(ctx context.Context, m *Monitor, selector ServerSelector) ([]*model.Server, error)
• type Cluster
  • func New(opts ...Option) (*Cluster, error)
  • func NewWithMonitor(monitor *Monitor, opts ...Option) (*Cluster, error)
  • func (c *Cluster) Close() error
  • func (c *Cluster) Model() *model.Cluster
  • func (c *Cluster) SelectServer(ctx context.Context, selector ServerSelector, ...) (*ops.SelectedServer, error)
• type Monitor
  • func StartMonitor(opts ...Option) (*Monitor, error)
  • func (m *Monitor) RequestImmediateCheck()
  • func (m *Monitor) ServerMonitor(addr model.Addr) (*server.Monitor, bool)
  • func (m *Monitor) Stop()
  • func (m *Monitor) Subscribe() (<-chan *model.Cluster, func(), error)
• type MonitorMode
• type Option
  • func WithConnString(cs connstring.ConnString) Option
  • func WithMode(mode MonitorMode) Option
  • func WithMoreServerOptions(opts ...server.Option) Option
  • func WithReplicaSetName(name string) Option
  • func WithSeedList(seedList ...string) Option
  • func WithServerOptions(opts ...server.Option) Option
• type Server
• type ServerSelector
  • func CompositeSelector(selectors []ServerSelector) ServerSelector
  • func LatencySelector(latency time.Duration) ServerSelector
  • func WriteSelector() ServerSelector

Variables

var ErrClusterClosed = errors.New("cluster is closed")

ErrClusterClosed occurs on an attempt to use a closed cluster.

Functions

func SelectServers

func SelectServers(ctx context.Context, m *Monitor, selector ServerSelector) ([]*model.Server, error)

SelectServers returns a list of server descriptions matching a given selector. SelectServers will only time out when its parent context is done.

Types

type Cluster

type Cluster struct {
	// contains filtered or unexported fields
}

Cluster represents a logical connection to a cluster.

func New

func New(opts ...Option) (*Cluster, error)

New creates a new cluster. Internally, it creates a new Monitor with which to monitor the state of the cluster. When the Cluster is closed, the monitor will be stopped.

func NewWithMonitor

func NewWithMonitor(monitor *Monitor, opts ...Option) (*Cluster, error)

NewWithMonitor creates a new Cluster from an existing monitor. When the cluster is closed, the monitor will not be stopped. Any unspecified options will have their default value pulled from the monitor. Any monitor specific options will be ignored.

func (*Cluster) Close

func (c *Cluster) Close() error

Close closes the cluster.

func (*Cluster) Model

func (c *Cluster) Model() *model.Cluster

Model gets a description of the cluster.

func (*Cluster) SelectServer

func (c *Cluster) SelectServer(ctx context.Context, selector ServerSelector,
	readPreference *readpref.ReadPref) (*ops.SelectedServer, error)

SelectServer selects a server given a selector. SelectServer complies with the server selection spec, and will time out after serverSelectionTimeout or when the parent context is done.

type Monitor

type Monitor struct {
	// contains filtered or unexported fields
}

Monitor continuously monitors the cluster for changes and reacts accordingly, adding or removing servers as necessary.

func StartMonitor

func StartMonitor(opts ...Option) (*Monitor, error)

StartMonitor begins monitoring a cluster.

func (*Monitor) RequestImmediateCheck

func (m *Monitor) RequestImmediateCheck()

RequestImmediateCheck will send heartbeats to all the servers in the cluster right away, instead of waiting for the heartbeat timeout.

func (*Monitor) ServerMonitor

func (m *Monitor) ServerMonitor(addr model.Addr) (*server.Monitor, bool)

ServerMonitor gets the server monitor for the specified endpoint. It is imperative that this monitor not be stopped.

func (*Monitor) Stop

func (m *Monitor) Stop()

Stop turns the monitor off.

func (*Monitor) Subscribe

func (m *Monitor) Subscribe() (<-chan *model.Cluster, func(), error)

Subscribe returns a channel on which all updated ClusterDescs will be sent. The channel will have a buffer size of one, and will be pre-populated with the current ClusterDesc. Subscribe also returns a function that, when called, will close the subscription channel and remove it from the list of subscriptions.

type MonitorMode

type MonitorMode uint8

MonitorMode indicates the mode with which to run the monitor.

const (
	AutomaticMode MonitorMode = iota
	SingleMode
)

MonitorMode constants.

type Option

type Option func(*config) error

Option configures a cluster.

func WithConnString

func WithConnString(cs connstring.ConnString) Option

WithConnString configures the cluster using the connection string.

func WithMode

func WithMode(mode MonitorMode) Option

WithMode configures the cluster's monitor mode. This option will be ignored when the cluster is created with a pre-existing monitor.

func WithMoreServerOptions

func WithMoreServerOptions(opts ...server.Option) Option

WithMoreServerOptions configures a cluster's server options for when a new server needs to get created. The options provided are appended to any current options and may override previously configured options.

func WithReplicaSetName

func WithReplicaSetName(name string) Option

WithReplicaSetName configures the cluster's default replica set name. This option will be ignored when the cluster is created with a pre-existing monitor.

func WithSeedList

func WithSeedList(seedList ...string) Option

WithSeedList configures a cluster's seed list. This option will be ignored when the cluster is created with a pre-existing monitor.

func WithServerOptions

func WithServerOptions(opts ...server.Option) Option

WithServerOptions configures a cluster's server options for when a new server needs to get created. The options provided overwrite all previously configured options.

type Server

type Server interface {
	// Connection gets a connection to the server.
	Connection(context.Context) (conn.Connection, error)
	// Model gets a description of the server.
	Model() *model.Server
}

Server represents a logical connection to a server.

type ServerSelector

type ServerSelector func(*model.Cluster, []*model.Server) ([]*model.Server, error)

ServerSelector is a function that selects a server.

func CompositeSelector

func CompositeSelector(selectors []ServerSelector) ServerSelector

CompositeSelector combines multiple selectors into a single selector.

func LatencySelector

func LatencySelector(latency time.Duration) ServerSelector

LatencySelector creates a ServerSelector which selects servers based on their latency.

func WriteSelector

func WriteSelector() ServerSelector

WriteSelector selects all the writable servers.