mon

Documentation

Index

• Variables
• func ReadAll(ctx context.Context, r ioctx.ReaderCtx, acct *BoundAccount) ([]byte, error)
• type BoundAccount
  • func MakeStandaloneBudget(capacity int64) BoundAccount
  • func (b *BoundAccount) Clear(ctx context.Context)
  • func (b *BoundAccount) Close(ctx context.Context)
  • func (b *BoundAccount) Empty(ctx context.Context)
  • func (b *BoundAccount) Grow(ctx context.Context, x int64) error
  • func (b *BoundAccount) Init(ctx context.Context, mon *BytesMonitor)
  • func (b *BoundAccount) Monitor() *BytesMonitor
  • func (b *BoundAccount) Resize(ctx context.Context, oldSz, newSz int64) error
  • func (b *BoundAccount) ResizeTo(ctx context.Context, newSz int64) error
  • func (b *BoundAccount) Shrink(ctx context.Context, delta int64)
  • func (b *BoundAccount) Used() int64
• type BytesMonitor
  • func NewMonitor(name string, res Resource, curCount *metric.Gauge, maxHist *metric.Histogram, ...) *BytesMonitor
  • func NewMonitorInheritWithLimit(name string, limit int64, m *BytesMonitor) *BytesMonitor
  • func NewMonitorWithLimit(name string, res Resource, limit int64, curCount *metric.Gauge, ...) *BytesMonitor
  • func NewUnlimitedMonitor(ctx context.Context, name string, res Resource, curCount *metric.Gauge, ...) *BytesMonitor
  • func (mm *BytesMonitor) AllocBytes() int64
  • func (mm *BytesMonitor) EmergencyStop(ctx context.Context)
  • func (mm *BytesMonitor) MakeBoundAccount() BoundAccount
  • func (mm *BytesMonitor) MaximumBytes() int64
  • func (mm *BytesMonitor) Name() string
  • func (mm *BytesMonitor) Resource() Resource
  • func (mm *BytesMonitor) SetMetrics(curCount *metric.Gauge, maxHist *metric.Histogram)
  • func (mm *BytesMonitor) Start(ctx context.Context, pool *BytesMonitor, reserved BoundAccount)
  • func (mm *BytesMonitor) Stop(ctx context.Context)
• type Resource

Variables

var DefaultPoolAllocationSize = envutil.EnvOrDefaultInt64("COCKROACH_ALLOCATION_CHUNK_SIZE", 10*1024)

DefaultPoolAllocationSize specifies the unit of allocation used by a monitor to reserve and release bytes to a pool.

Functions

func ReadAll

func ReadAll(ctx context.Context, r ioctx.ReaderCtx, acct *BoundAccount) ([]byte, error)

ReadAll is like ioctx.ReadAll except it additionally asks the BoundAccount acct permission, if it is non-nil, it grows its buffer while reading. When the caller releases the returned slice it shrink the bound account by its cap.

Types

type BoundAccount

type BoundAccount struct {

	// Mu, if non-nil, is used in some methods such as Grow and Shrink.
	Mu *syncutil.Mutex
	// contains filtered or unexported fields
}

BoundAccount tracks the cumulated allocations for one client of a pool or monitor. BytesMonitor has an account to its pool; BytesMonitor clients have an account to the monitor. This allows each client to release all the bytes at once when it completes its work. Internally, BoundAccount amortizes allocations from whichever BoundAccount it is associated with by allocating additional memory and parceling it out (see BoundAccount.reserved). A nil BoundAccount acts as an unlimited account for which growing and shrinking are noops.

See the comments in bytes_usage.go for a fuller picture of how these accounts are used in CockroachDB.

A normal BoundAccount is not safe for concurrent use by multiple goroutines, however if the Mu field is set to a non-nil mutex, some methods such as Grow, Shrink, and Resize calls will lock and unlock that mutex making them safe; such methods are identified in their comments.

func MakeStandaloneBudget

func MakeStandaloneBudget(capacity int64) BoundAccount

MakeStandaloneBudget creates a BoundAccount suitable for root monitors.

func (*BoundAccount) Clear

func (b *BoundAccount) Clear(ctx context.Context)

Clear releases all the cumulated allocations of an account at once and primes it for reuse.

func (*BoundAccount) Close

func (b *BoundAccount) Close(ctx context.Context)

Close releases all the cumulated allocations of an account at once.

func (*BoundAccount) Empty

func (b *BoundAccount) Empty(ctx context.Context)

Empty shrinks the account to use 0 bytes. Previously used memory is returned to the reserved buffer, which is subsequently released such that at most poolAllocationSize is reserved.

func (*BoundAccount) Grow

func (b *BoundAccount) Grow(ctx context.Context, x int64) error

Grow is an accessor for b.mon.GrowAccount.

If Mu is set, it is safe for use by concurrent goroutines.

func (*BoundAccount) Init

func (b *BoundAccount) Init(ctx context.Context, mon *BytesMonitor)

Init initializes a BoundAccount, connecting it to the given monitor. It is similar to MakeBoundAccount, but allows the caller to save a BoundAccount allocation.

func (*BoundAccount) Monitor

func (b *BoundAccount) Monitor() *BytesMonitor

Monitor returns the BytesMonitor to which this account is bound. The return value can be nil.

func (*BoundAccount) Resize

func (b *BoundAccount) Resize(ctx context.Context, oldSz, newSz int64) error

Resize requests a size change for an object already registered in an account. The reservation is not modified if the new allocation is refused, so that the caller can keep using the original item without an accounting error. This is better than calling ClearAccount then GrowAccount because if the Clear succeeds and the Grow fails the original item becomes invisible from the perspective of the monitor.

If one is interested in specifying the new size of the account as a whole (as opposed to resizing one object among many in the account), ResizeTo() should be used.

If Mu is set, it is safe for use by concurrent goroutines.

func (*BoundAccount) ResizeTo

func (b *BoundAccount) ResizeTo(ctx context.Context, newSz int64) error

ResizeTo resizes (grows or shrinks) the account to a specified size.

If Mu is set, it is safe for use by concurrent goroutines.

func (*BoundAccount) Shrink

func (b *BoundAccount) Shrink(ctx context.Context, delta int64)

Shrink releases part of the cumulated allocations by the specified size.

If Mu is set, it is safe for use by concurrent goroutines.

func (*BoundAccount) Used

func (b *BoundAccount) Used() int64

Used returns the number of bytes currently allocated through this account. If Mu is set, it is safe for use by concurrent goroutines.

type BytesMonitor

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

BytesMonitor defines an object that can track and limit memory/disk usage by other CockroachDB components. The monitor must be set up via Start/Stop before and after use. The various counters express sizes in bytes.

func NewMonitor

func NewMonitor(
	name string,
	res Resource,
	curCount *metric.Gauge,
	maxHist *metric.Histogram,
	increment int64,
	noteworthy int64,
	settings *cluster.Settings,
) *BytesMonitor

NewMonitor creates a new monitor. Arguments:

• name is used to annotate log messages, can be used to distinguish monitors.

• resource specifies what kind of resource the monitor is tracking allocations for (e.g. memory or disk).

• curCount and maxHist are the metric objects to update with usage statistics. Can be nil.

• increment is the block size used for upstream allocations from the pool. Note: if set to 0 or lower, the default pool allocation size is used.

• noteworthy determines the minimum total allocated size beyond which the monitor starts to log increases. Use 0 to always log or math.MaxInt64 to never log.

func NewMonitorInheritWithLimit

func NewMonitorInheritWithLimit(name string, limit int64, m *BytesMonitor) *BytesMonitor

NewMonitorInheritWithLimit creates a new monitor with a limit local to this monitor with all other attributes inherited from the passed in monitor. Note on metrics and inherited monitors. When using pool to share resource, downstream monitors must not use the same metric objects as pool monitor to avoid reporting the same allocation multiple times. Downstream monitors should use their own metrics as needed by using BytesMonitor.SetMetrics function. Also note that because monitors pre-allocate resources from pool in chunks, those chunks would be reported as used by pool while downstream monitors will not.

func NewMonitorWithLimit

func NewMonitorWithLimit(
	name string,
	res Resource,
	limit int64,
	curCount *metric.Gauge,
	maxHist *metric.Histogram,
	increment int64,
	noteworthy int64,
	settings *cluster.Settings,
) *BytesMonitor

NewMonitorWithLimit creates a new monitor with a limit local to this monitor.

func NewUnlimitedMonitor

func NewUnlimitedMonitor(
	ctx context.Context,
	name string,
	res Resource,
	curCount *metric.Gauge,
	maxHist *metric.Histogram,
	noteworthy int64,
	settings *cluster.Settings,
) *BytesMonitor

NewUnlimitedMonitor creates a new monitor and starts the monitor in "detached" mode without a pool and without a maximum budget.

func (*BytesMonitor) AllocBytes

func (mm *BytesMonitor) AllocBytes() int64

AllocBytes returns the current number of allocated bytes in this monitor.

func (*BytesMonitor) EmergencyStop

func (mm *BytesMonitor) EmergencyStop(ctx context.Context)

EmergencyStop completes a monitoring region, and disables checking that all accounts have been closed. This is useful when recovering from panics so that we don't panic again.

func (*BytesMonitor) MakeBoundAccount

func (mm *BytesMonitor) MakeBoundAccount() BoundAccount

MakeBoundAccount creates a BoundAccount connected to the given monitor.

func (*BytesMonitor) MaximumBytes

func (mm *BytesMonitor) MaximumBytes() int64

MaximumBytes returns the maximum number of bytes that were allocated by this monitor at one time since it was started.

func (*BytesMonitor) Name

func (mm *BytesMonitor) Name() string

Name returns the name of the monitor.

func (*BytesMonitor) Resource

func (mm *BytesMonitor) Resource() Resource

Resource returns the type of the resource the monitor is tracking.

func (*BytesMonitor) SetMetrics

func (mm *BytesMonitor) SetMetrics(curCount *metric.Gauge, maxHist *metric.Histogram)

SetMetrics sets the metric objects for the monitor.

func (*BytesMonitor) Start

func (mm *BytesMonitor) Start(ctx context.Context, pool *BytesMonitor, reserved BoundAccount)

Start begins a monitoring region. Arguments:

• pool is the upstream monitor that provision allocations exceeding the pre-reserved budget. If pool is nil, no upstream allocations are possible and the pre-reserved budget determines the entire capacity of this monitor.

- reserved is the pre-reserved budget (see above).

func (*BytesMonitor) Stop

func (mm *BytesMonitor) Stop(ctx context.Context)

Stop completes a monitoring region.

type Resource

type Resource interface {
	NewBudgetExceededError(requestedBytes int64, reservedBytes int64, budgetBytes int64) error
}

Resource is an interface used to abstract the specifics of tracking bytes usage by different types of resources.

var DiskResource Resource = diskResource{}

DiskResource is a utility singleton used as an argument when creating a BytesMonitor to indicate that the monitor will be tracking disk usage.

var MemoryResource Resource = memoryResource{}

MemoryResource is a utility singleton used as an argument when creating a BytesMonitor to indicate that the monitor will be tracking memory usage.