cursor

Documentation

Overview

Package cursor provides access to cursor registry.

The implementation of the cursor and registry is quite complicated and entangled. That's because there are many cases when the iterator (and the underlying database connection) must be closed to free resources, including when no handler and backend code is running; for example, when the client disconnects between `getMore` commands. At the same time, we want to shift complexity away from the handler and from backend implementations because they are already quite complex. The current design enables ease of use at the expense of the implementation complexity.

Index

• type Cursor
  • func (c *Cursor) Close()
  • func (c *Cursor) Next() (struct{}, *types.Document, error)
  • func (c *Cursor) Reset(iter types.DocumentsIterator) error
• type NewParams
• type Registry
  • func NewRegistry(l *zap.Logger) *Registry
  • func (r *Registry) All() []*Cursor
  • func (r *Registry) Close()
  • func (r *Registry) CloseAndRemove(c *Cursor)
  • func (r *Registry) Collect(ch chan<- prometheus.Metric)
  • func (r *Registry) Describe(ch chan<- *prometheus.Desc)
  • func (r *Registry) Get(id int64) *Cursor
  • func (r *Registry) NewCursor(ctx context.Context, iter types.DocumentsIterator, params *NewParams) *Cursor
• type Type
  • func (i Type) String() string

Types

type Cursor

type Cursor struct {
	*NewParams

	ID int64
	// contains filtered or unexported fields
}

Cursor allows clients to iterate over a result set (or multiple sets for tailable cursors).

It implements types.DocumentsIterator interface by wrapping another iterator with additional metadata and registration in the registry.

Closing the cursor closes the underlying iterator. For normal cursors, it also removes it from the registry. Tailable cursors are not removed in that case.

func (*Cursor) Close

func (c *Cursor) Close()

Close implements types.DocumentsIterator interface.

It closes the underlying iterator. For normal cursors, it also removes it from the registry.

func (*Cursor) Next

func (c *Cursor) Next() (struct{}, *types.Document, error)

Next implements types.DocumentsIterator interface.

func (*Cursor) Reset

func (c *Cursor) Reset(iter types.DocumentsIterator) error

Reset replaces the underlying iterator with a given one and advanced it until the last known record ID is reached.

It should be used only with tailable cursors.

type NewParams

type NewParams struct {
	// Data stored, but not used by this package.
	// Used to pass *handler.findCursorData between `find` and `getMore` command implementations.
	// Stored as any to avoid dependency cycle.
	Data any

	// those fields are used for limited authorization checks
	// before we implement proper authz and/or sessions
	DB         string
	Collection string
	Username   string

	Type         Type
	ShowRecordID bool
	// contains filtered or unexported fields
}

NewParams represent parameters for NewCursor.

type Registry

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

Registry stores cursors.

func NewRegistry

func NewRegistry(l *zap.Logger) *Registry

NewRegistry creates a new Registry.

func (*Registry) All

func (r *Registry) All() []*Cursor

All returns a shallow copy of all stored cursors.

func (*Registry) Close

func (r *Registry) Close()

Close waits for all cursors to be closed and removed from the registry.

func (*Registry) CloseAndRemove

func (r *Registry) CloseAndRemove(c *Cursor)

CloseAndRemove closes the given cursors, then removes it from the registry.

func (*Registry) Collect

func (r *Registry) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector.

func (*Registry) Describe

func (r *Registry) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

func (*Registry) Get

func (r *Registry) Get(id int64) *Cursor

Get returns stored cursor by ID, or nil.

func (*Registry) NewCursor

func (r *Registry) NewCursor(ctx context.Context, iter types.DocumentsIterator, params *NewParams) *Cursor

NewCursor creates and stores a new cursor.

The cursor of any type will be closed automatically when a given context is canceled, even if the cursor is not being used at that time.

type Type

type Type int

Type represents a cursor type.

const (

	// Normal represents a normal cursor.
	Normal Type

	// Tailable represents a tailable cursor.
	Tailable

	// TailableAwait represents a tailable and blocking cursor.
	TailableAwait
)

func (Type) String

func (i Type) String() string