store

type ErrDisabled interface {
	ErrDisabled() string
}

type ErrNotFound interface {
	ErrNotFound() string
}

type GroupStore interface {
	Store
	// Lookup will return (timestampmicro, length, err) for (parentKeyA,
	// parentKeyB, childKeyA, childKeyB).
	//
	// Note that err == ErrNotFound with timestampmicro == 0 indicates
	// (parentKeyA, parentKeyB, childKeyA, childKeyB) was not known at all
	// whereas err == ErrNotFound with timestampmicro != 0 indicates
	// (parentKeyA, parentKeyB, childKeyA, childKeyB) was known and had a
	// deletion marker (aka tombstone).
	Lookup(ctx context.Context, parentKeyA, parentKeyB, childKeyA, childKeyB uint64) (timestampmicro int64, length uint32, err error)
	// LookupGroup returns all the (childKeyA, childKeyB, timestampMicro,
	// length) items matching under (parentKeyA, parentKeyB).
	LookupGroup(ctx context.Context, parentKeyA, parentKeyB uint64) ([]LookupGroupItem, error)
	// Read will return (timestampmicro, value, err) for (parentKeyA,
	// parentKeyB, childKeyA, childKeyB); if an incoming value is provided, any
	// value read from the store will be appended to it and the whole returned
	// (useful to reuse an existing []byte).
	//
	// Note that err == ErrNotFound with timestampmicro == 0 indicates
	// (parentKeyA, parentKeyB, childKeyA, childKeyB) was not known at all
	// whereas err == ErrNotFound with timestampmicro != 0 indicates
	// (parentKeyA, parentKeyB, childKeyA, childKeyB) was known and had a
	// deletion marker (aka tombstone).
	Read(ctx context.Context, parentKeyA, parentKeyB, childKeyA, childKeyB uint64, value []byte) (timestampmicro int64, rvalue []byte, err error)
	// Write stores (timestampmicro, value) for (parentKeyA, parentKeyB,
	// childKeyA, childKeyB) and returns the previously stored timestampmicro
	// or returns any error; a newer timestampmicro already in place is not
	// reported as an error. Note that with a Write and a Delete for the exact
	// same timestampmicro, the Delete wins.
	// ReadGroup returns all the (childKeyA, childKeyB, timestampMicro, value)
	// items matching under (parentKeyA, parentKeyB).
	ReadGroup(ctx context.Context, parentKeyA, parentKeyB uint64) ([]ReadGroupItem, error)
	Write(ctx context.Context, parentKeyA, parentKeyB, childKeyA, childKeyB uint64, timestampmicro int64, value []byte) (oldtimestampmicro int64, err error)
	// Delete stores timestampmicro for (parentKeyA, parentKeyB, childKeyA,
	// childKeyB) and returns the previously stored timestampmicro or returns
	// any error; a newer timestampmicro already in place is not reported as an
	// error. Note that with a Write and a Delete for the exact same
	// timestampmicro, the Delete wins.
	Delete(ctx context.Context, parentKeyA, parentKeyB, childKeyA, childKeyB uint64, timestampmicro int64) (oldtimestampmicro int64, err error)
}

type GroupStoreConfig struct {
	// Scale sets how much to scale the default values by; this can reduce
	// memory usage for systems where the store isn't the only thing running on
	// the hardware. Note that this will *not* scale explictly set values, just
	// the values if they fallback to the defaults.
	Scale float64
	// Logger defines where log output will go. This library has minimal log
	// output (most meta data is sent via metrics) but some errors and debug
	// logging does exist. If not set, the logger will default to
	// zap.NewProduction()
	Logger *zap.Logger
	// LoggerName is used as a prefix when setting the "name" field with log
	// messages. For example, given a LoggerName of "mystoreapp", this library
	// would log under names such as "mystoreapp.compaction" and
	// "mystoreapp.recovery".
	LoggerName string
	// Rand sets the rand.Rand to use as a random data source. Defaults to a
	// new randomizer based on the current time.
	Rand *rand.Rand
	// Path sets the path where group files will be written; grouptoc files
	// will also be written here unless overridden with PathTOC. Defaults to
	// the current working directory.
	Path string
	// PathTOC sets the path where grouptoc files will be written. Defaults to
	// the Path value.
	PathTOC string
	// ValueCap indicates the maximum number of bytes any given value may be.
	// Defaults to 1,048,576 bytes.
	ValueCap int
	// Workers indicates how many goroutines may be used for various tasks
	// (processing incoming writes and batching them to disk, background tasks,
	// etc.). This will also have an impact on memory usage. Defaults to
	// GOMAXPROCS.
	Workers int
	// ChecksumInterval indicates how many bytes are output to a file before a
	// 4-byte checksum is also output. Defaults to 65,532 bytes.
	ChecksumInterval int
	// PageSize controls the size of each chunk of memory allocated. Defaults
	// to 4,194,304 bytes.
	PageSize int
	// WritePagesPerWorker controls how many pages are created per worker for
	// caching recently written values. Defaults to 3.
	WritePagesPerWorker int
	// GroupLocMap allows overriding the default GroupLocMap, an interface
	// used by GroupStore for tracking the mappings from keys to the locations
	// of their values. Defaults to
	// github.com/gholt/locmap.NewGroupLocMap().
	GroupLocMap locmap.GroupLocMap
	// MsgRing sets the ring.MsgRing to use for determining the key ranges the
	// GroupStore is responsible for as well as providing methods to send
	// messages to other nodes.
	MsgRing msgring.MsgRing
	// MsgCap indicates the maximum bytes for outgoing messages. Defaults to
	// 16,777,216 bytes.
	MsgCap int
	// MsgTimeout indicates the maximum milliseconds a message can be pending
	// before just discarding it. Defaults to 250 milliseconds.
	MsgTimeout int
	// FileCap indicates how large a file can be before closing it and opening
	// a new one. Defaults to 4,294,967,295 bytes.
	FileCap int
	// FileReaders indicates how many open file descriptors are allowed per
	// file for reading. Defaults to Workers.
	FileReaders int
	// RecoveryBatchSize indicates how many keys to set in a batch while
	// performing recovery (initial start up). Defaults to 1,048,576 keys.
	RecoveryBatchSize int
	// TombstoneDiscardInterval indicates the minimum number of seconds between
	// the starts of background passes to discard expired tombstones [deletion
	// markers]. If set to 300 seconds and a pass takes 100 seconds to run, it
	// will wait 200 seconds (with a small amount of randomization) before
	// starting the next pass. Default: 300 seconds
	TombstoneDiscardInterval int
	// TombstoneDiscardBatchSize indicates how many items to queue up before
	// pausing a scan, issuing the actual discards, and resuming the scan
	// again. Defaults to 1,048,576 items.
	TombstoneDiscardBatchSize int
	// TombstoneAge indicates how many seconds old a deletion marker may be
	// before it is permanently removed. Defaults to 14,400 seconds (4 hours).
	TombstoneAge int
	// TombstoneDiscardWorkers indicates how many goroutines may be used for
	// discard passes (discarding expired tombstones [deletion markers]).
	// Defaults to 1 worker.
	TombstoneDiscardWorkers int
	// ReplicationIgnoreRecent indicates how many seconds old a value should be
	// before it is included in replication processing. Defaults to 60 seconds.
	ReplicationIgnoreRecent int
	// OutPullReplicationInterval is much like TombstoneDiscardInterval but for
	// outgoing pull replication passes. Default: 60 seconds
	OutPullReplicationInterval int
	// OutPullReplicationWorkers indicates how many goroutines may be used for
	// an outgoing pull replication pass. Defaults to Workers / 10 with a
	// minimum of 1.
	OutPullReplicationWorkers int
	// OutPullReplicationMsgs indicates how many outgoing pull-replication
	// messages can be buffered before blocking on creating more. Defaults to
	// OutPullReplicationWorkers * 4.
	OutPullReplicationMsgs int
	// OutPullReplicationBloomN indicates the N-factor for the outgoing
	// pull-replication bloom filters. This indicates how many keys the bloom
	// filter can reasonably hold and, in combination with the P-factor,
	// affects memory usage. Defaults to 1,000,000.
	OutPullReplicationBloomN int
	// OutPullReplicationBloomP indicates the P-factor for the outgoing
	// pull-replication bloom filters. This indicates the desired percentage
	// chance of a collision within the bloom filter and, in combination with
	// the N-factor, affects memory usage. Defaults to 0.001.
	OutPullReplicationBloomP float64
	// OutPullReplicationMsgTimeout indicates the maximum milliseconds an
	// outgoing pull replication message can be pending before just discarding
	// it. Defaults to MsgTimeout.
	OutPullReplicationMsgTimeout int
	// InPullReplicationWorkers indicates how many incoming pull-replication
	// messages can be processed at the same time. Defaults to Workers.
	InPullReplicationWorkers int
	// InPullReplicationMsgs indicates how many incoming pull-replication
	// messages can be buffered before dropping additional ones. Defaults to
	// InPullReplicationWorkers * 4.
	InPullReplicationMsgs int
	// InPullReplicationResponseMsgTimeout indicates the maximum milliseconds
	// an outgoing response message to an incoming pull replication message can
	// be pending before just discarding it. Defaults to MsgTimeout.
	InPullReplicationResponseMsgTimeout int
	// PushReplicationInterval is much like TombstoneDiscardInterval but for
	// outgoing push replication passes. Default: 60 seconds
	PushReplicationInterval int
	// PushReplicationWorkers indicates how many goroutines may be used for an
	// outgoing push replication pass. Defaults to Workers / 10 with minimum of
	// 1.
	PushReplicationWorkers int
	// PushReplicationMsgTimeout indicates the maximum milliseconds an
	// outgoing push replication message can be pending before just discarding
	// it. Defaults to MsgTimeout.
	PushReplicationMsgTimeout int
	// BulkSetMsgCap indicates the maximum bytes for bulk-set messages.
	// Defaults to MsgCap.
	BulkSetMsgCap int
	// OutBulkSetMsgs indicates how many outgoing bulk-set messages can be
	// buffered before blocking on creating more. Defaults to
	// PushReplicationWorkers * 4.
	OutBulkSetMsgs int
	// InBulkSetWorkers indicates how many incoming bulk-set messages can be
	// processed at the same time. Defaults to Workers.
	InBulkSetWorkers int
	// InBulkSetMsgs indicates how many incoming bulk-set messages can be
	// buffered before dropping additional ones. Defaults to InBulkSetWorkers *
	// 4.
	InBulkSetMsgs int
	// InBulkSetResponseMsgTimeout indicates the maximum milliseconds a
	// response message to an incoming bulk-set message can be pending before
	// just discarding it. Defaults to MsgTimeout.
	InBulkSetResponseMsgTimeout int
	// BulkSetAckMsgCap indicates the maximum bytes for bulk-set-ack messages.
	// Defaults to MsgCap.
	BulkSetAckMsgCap int
	// InBulkSetAckWorkers indicates how many incoming bulk-set-ack messages
	// can be processed at the same time. Defaults to Workers.
	InBulkSetAckWorkers int
	// InBulkSetAckMsgs indicates how many incoming bulk-set-ack messages can
	// be buffered before dropping additional ones. Defaults to
	// InBulkSetAckWorkers * 4.
	InBulkSetAckMsgs int
	// OutBulkSetAckMsgs indicates how many outgoing bulk-set-ack messages can
	// be buffered before blocking on creating more. Defaults to
	// InBulkSetWorkers * 4.
	OutBulkSetAckMsgs int
	// CompactionInterval is much like TombstoneDiscardInterval but for
	// compaction passes. Default: 600 seconds
	CompactionInterval int
	// CompactionWorkers indicates how much concurrency is allowed for
	// compaction. Defaults to 1.
	CompactionWorkers int
	// CompactionThreshold indicates how much waste a given file may have
	// before it is compacted. Defaults to 0.10 (10%).
	CompactionThreshold float64
	// CompactionAgeThreshold indicates how old a given file must be before it
	// is considered for compaction. Defaults to 300 seconds.
	CompactionAgeThreshold int
	// DiskFreeDisableThreshold controls when to automatically disable writes;
	// the number is in bytes. If the number of free bytes on either the Path
	// or TOCPath device falls below this threshold, writes will be
	// automatically disabled.
	// 0 will use the default; 1 will disable the check.
	// default: 8,589,934,592 (8G)
	DiskFreeDisableThreshold uint64
	// DiskFreeReenableThreshold controls when to automatically re-enable
	// writes; the number is in bytes. If writes are automatically disabled and
	// the number of free bytes on each of the Path or TOCPath devices rises
	// above this threshold, writes will be automatically re-enabled. A
	// negative value will turn off this check.
	// 0 will use the default; 1 will disable the check.
	// default: 17,179,869,184 (16G)
	DiskFreeReenableThreshold uint64
	// DiskUsageDisableThreshold controls when to automatically disable writes;
	// the number is a percentage (1 == 100%). If the percentage used on either
	// the Path or TOCPath device grows above this threshold, writes will be
	// automatically disabled.
	// 0 will use the default; a negative value will disable the check.
	// default: 0.94 (94%)
	DiskUsageDisableThreshold float64
	// DiskUsageReenableThreshold controls when to automatically re-enable
	// writes; the number is a percentage (1 == 100%). If writes are
	// automatically disabled and the percentage used on each of the Path or
	// TOCPath devices falls below this threshold, writes will be automatically
	// re-enabled.
	// 0 will use the default; a negative value will disable the check.
	// default: 0.90 (90%)
	DiskUsageReenableThreshold float64
	// FlusherThreshold sets the number of to-disk modifications controlling
	// the once-a-minute automatic flusher. If there are less than this
	// setting's number of modifications for a minute, the store's Flush method
	// will be called. This is so relatively idle stores won't just leave the
	// last few modifications sitting only in memory for too long, but without
	// penalizing active stores that will already be sending recent
	// modifications to disk as ever more recent modifications occur.
	// 0 will use the default; a negative value will disable the check.
	// default is the number of entries that are guaranteed to fill a memory
	// page; this depends on the PageSize value and the internal struct size
	// for the store.
	FlusherThreshold int32
	// AuditInterval is much like TombstoneDiscardInterval but for audit
	// passes. Default: 604,800 seconds (1 week).
	AuditInterval int
	// AuditAgeThreshold indicates how old a given file must be before it
	// is considered for an audit. Defaults to 604,800 seconds (1 week).
	AuditAgeThreshold int
	// MemFreeDisableThreshold controls when to automatically disable writes;
	// the number is in bytes. If the number of free bytes of memory falls
	// below this threshold, writes will be automatically disabled.
	// 0 will use the default; 1 will disable the check.
	// default: 134,217,728 (128M)
	MemFreeDisableThreshold uint64
	// MemFreeReenableThreshold controls when to automatically re-enable
	// writes; the number is in bytes. If writes are automatically disabled and
	// the number of free bytes of memory rises above this threshold, writes
	// will be automatically re-enabled. A negative value will turn off this
	// check.
	// 0 will use the default; 1 will disable the check.
	// default: 268,435,456 (256M)
	MemFreeReenableThreshold uint64
	// MemUsageDisableThreshold controls when to automatically disable writes;
	// the number is a percentage (1 == 100%). If the percentage of used memory
	// grows above this threshold, writes will be automatically disabled.
	// 0 will use the default; a negative value will disable the check.
	// default: 0.94 (94%)
	MemUsageDisableThreshold float64
	// MemUsageReenableThreshold controls when to automatically re-enable
	// writes; the number is a percentage (1 == 100%). If writes are
	// automatically disabled and the percentage of used memory falls below
	// this threshold, writes will be automatically re-enabled.
	// 0 will use the default; a negative value will disable the check.
	// default: 0.90 (90%)
	MemUsageReenableThreshold float64
	// contains filtered or unexported fields
}

type GroupStoreStats struct {
	// Values is the number of values in the GroupStore.
	Values uint64
	// ValuesBytes is the number of bytes of the values in the GroupStore.
	ValueBytes uint64
	// Lookups is the number of calls to Lookup.
	Lookups int32
	// LookupErrors is the number of errors returned by Lookup; not-found
	// errors do not count here.
	LookupErrors int32

	// LookupGroups is the number of calls to LookupGroup.
	LookupGroups int32
	// LookupGroupItems is the number of items LookupGroup has encountered.
	LookupGroupItems int32
	// LookupGroupErrors is the number of errors returned by LookupGroup.
	LookupGroupErrors int32

	// Reads is the number of calls to Read.
	Reads int32
	// ReadErrors is the number of errors returned by Read; not-found errors do
	// not count here.
	ReadErrors int32

	// ReadGroups is the number of calls to ReadGroup.
	ReadGroups int32
	// ReadGroupItems is the number of items ReadGroup has encountered.
	ReadGroupItems int32
	// ReadGroupErrors is the number of errors returned by ReadGroup.
	ReadGroupErrors int32

	// Writes is the number of calls to Write.
	Writes int32
	// WriteErrors is the number of errors returned by Write.
	WriteErrors int32
	// WritesOverridden is the number of calls to Write that resulted in no
	// change.
	WritesOverridden int32
	// Deletes is the number of calls to Delete.
	Deletes int32
	// DeleteErrors is the number of errors returned by Delete.
	DeleteErrors int32
	// DeletesOverridden is the number of calls to Delete that resulted in no
	// change.
	DeletesOverridden int32
	// OutBulkSets is the number of outgoing bulk-set messages in response to
	// incoming pull replication messages.
	OutBulkSets int32
	// OutBulkSetValues is the number of values in outgoing bulk-set messages;
	// these bulk-set messages are those in response to incoming
	// pull-replication messages.
	OutBulkSetValues int32
	// OutBulkSetPushes is the number of outgoing bulk-set messages due to push
	// replication.
	OutBulkSetPushes int32
	// OutBulkSetPushValues is the number of values in outgoing bulk-set
	// messages; these bulk-set messages are those due to push replication.
	OutBulkSetPushValues int32
	// OutPushReplicationNanoseconds is how long the last out push replication
	// pass took.
	OutPushReplicationNanoseconds int64
	// InBulkSets is the number of incoming bulk-set messages.
	InBulkSets int32
	// InBulkSetDrops is the number of incoming bulk-set messages dropped due
	// to the local system being overworked at the time.
	InBulkSetDrops int32
	// InBulkSetInvalids is the number of incoming bulk-set messages that
	// couldn't be parsed.
	InBulkSetInvalids int32
	// InBulkSetWrites is the number of writes due to incoming bulk-set
	// messages.
	InBulkSetWrites int32
	// InBulkSetWriteErrors is the number of errors returned from writes due to
	// incoming bulk-set messages.
	InBulkSetWriteErrors int32
	// InBulkSetWritesOverridden is the number of writes from incoming bulk-set
	// messages that result in no change.
	InBulkSetWritesOverridden int32
	// OutBulkSetAcks is the number of outgoing bulk-set-ack messages.
	OutBulkSetAcks int32
	// InBulkSetAcks is the number of incoming bulk-set-ack messages.
	InBulkSetAcks int32
	// InBulkSetAckDrops is the number of incoming bulk-set-ack messages
	// dropped due to the local system being overworked at the time.
	InBulkSetAckDrops int32
	// InBulkSetAckInvalids is the number of incoming bulk-set-ack messages
	// that couldn't be parsed.
	InBulkSetAckInvalids int32
	// InBulkSetAckWrites is the number of writes (for local removal) due to
	// incoming bulk-set-ack messages.
	InBulkSetAckWrites int32
	// InBulkSetAckWriteErrors is the number of errors returned from writes due
	// to incoming bulk-set-ack messages.
	InBulkSetAckWriteErrors int32
	// InBulkSetAckWritesOverridden is the number of writes from incoming
	// bulk-set-ack messages that result in no change.
	InBulkSetAckWritesOverridden int32
	// OutPullReplications is the number of outgoing pull-replication messages.
	OutPullReplications int32
	// OutPullReplicationNanoseconds is how long the last out pull replication
	// pass took.
	OutPullReplicationNanoseconds int64
	// InPullReplications is the number of incoming pull-replication messages.
	InPullReplications int32
	// InPullReplicationDrops is the number of incoming pull-replication
	// messages droppped due to the local system being overworked at the time.
	InPullReplicationDrops int32
	// InPullReplicationInvalids is the number of incoming pull-replication
	// messages that couldn't be parsed.
	InPullReplicationInvalids int32
	// ExpiredDeletions is the number of recent deletes that have become old
	// enough to be completely discarded.
	ExpiredDeletions int32
	// TombstoneDiscardNanoseconds is how long the last tombstone discard pass
	// took.
	TombstoneDiscardNanoseconds int64
	// CompactionNanoseconds is how long the last compaction pass took.
	CompactionNanoseconds int64
	// Compactions is the number of disk file sets compacted due to their
	// contents exceeding a staleness threshold. For example, this happens when
	// enough of the values have been overwritten or deleted in more recent
	// operations.
	Compactions int32
	// SmallFileCompactions is the number of disk file sets compacted due to
	// the entire file size being too small. For example, this may happen when
	// the store is shutdown and restarted.
	SmallFileCompactions int32
	// DiskFree is the number of bytes free on the device containing the
	// Config.Path for the defaultGroupStore.
	DiskFree uint64
	// DiskUsed is the number of bytes used on the device containing the
	// Config.Path for the defaultGroupStore.
	DiskUsed uint64
	// DiskSize is the size in bytes of the device containing the Config.Path
	// for the defaultGroupStore.
	DiskSize uint64
	// DiskFreeTOC is the number of bytes free on the device containing the
	// Config.PathTOC for the defaultGroupStore.
	DiskFreeTOC uint64
	// DiskUsedTOC is the number of bytes used on the device containing the
	// Config.PathTOC for the defaultGroupStore.
	DiskUsedTOC uint64
	// DiskSizeTOC is the size in bytes of the device containing the
	// Config.PathTOC for the defaultGroupStore.
	DiskSizeTOC uint64
	// MemFree is the number of bytes of free memory.
	MemFree uint64
	// MemUsed is the number of bytes of used memory.
	MemUsed uint64
	// MemSize is the size in bytes of total memory on the system.
	MemSize uint64
	// ReadOnly indicates when the system has been put in read-only mode,
	// whether by DisableWrites or automatically by the watcher.
	ReadOnly bool
	// AuditNanoseconds is how long the last audit pass took.
	AuditNanoseconds int64
	// contains filtered or unexported fields
}

type LookupGroupItem struct {
	ChildKeyA      uint64
	ChildKeyB      uint64
	TimestampMicro int64
	Length         uint32
}

type ReadGroupItem struct {
	ChildKeyA      uint64
	ChildKeyB      uint64
	TimestampMicro int64
	Value          []byte
}

type Store interface {
	// Startup will start up everything needed to start using the Store or
	// return an error; on creation, a Store will not yet be started up.
	Startup(ctx context.Context) error
	// Shutdown will ensure buffered data is written to disk and will shutdown
	// the Store; the Store will be unusable until Startup is called again.
	Shutdown(ctx context.Context) error
	// EnableWrites will switch the Store to read-write mode, assuming the
	// Store supports writes; this is the default mode of most stores after
	// Startup, but it doesn't hurt to call it anyway to be sure.
	EnableWrites(ctx context.Context) error
	// DisableWrites will switch the Store to a read-only mode until
	// EnableWrites is called.
	DisableWrites(ctx context.Context) error
	// Flush will ensure buffered data, at the time of the call, is written to
	// disk.
	Flush(ctx context.Context) error
	// AuditPass will immediately execute a pass at full speed to check the
	// on-disk data for errors rather than waiting for the next interval to run
	// the standard slow-audit pass. If a pass is currently executing, it will
	// be stopped and restarted so that a call to this function ensures one
	// complete pass occurs.
	AuditPass(ctx context.Context) error
	// Stats returns overall information about the state of the Store. Note
	// that this can be an expensive call; debug = true will make it even more
	// expensive.
	//
	// Note that this function returns a fmt.Stringer because other
	// implementations of a Store shouldn't be tied to this package's
	// implementation. But, a quick casting attempt to *ValueStoreStats can be
	// done to gain access to individual fields.
	//
	// For this package's implementation, the public counter fields returned in
	// the stats will reset with each read. In other words, if stats.WriteCount
	// has the value 10 and no more writes occur before Stats() is called
	// again, that second stats.WriteCount will have the value 0.
	//
	// The various values reported when debug=true are left undocumented
	// because they are subject to change. They are only emitted when the
	// stats.String() is called.
	Stats(ctx context.Context, debug bool) (fmt.Stringer, error)
	// ValueCap returns the maximum length of a value the Store can accept.
	ValueCap(ctx context.Context) (uint32, error)
}

type ValueStore interface {
	Store
	// Lookup will return (timestampmicro, length, err) for (keyA, keyB).
	//
	// Note that err == ErrNotFound with timestampmicro == 0 indicates (keyA,
	// keyB) was not known at all whereas err == ErrNotFound with
	// timestampmicro != 0 indicates (keyA, keyB) was known and had a deletion
	// marker (aka tombstone).
	Lookup(ctx context.Context, keyA uint64, keyB uint64) (int64, uint32, error)
	// Read will return (timestampmicro, value, err) for (keyA, keyB); if an
	// incoming value is provided, any value read from the store will be
	// appended to it and the whole returned (useful to reuse an existing
	// []byte).
	//
	// Note that err == ErrNotFound with timestampmicro == 0 indicates (keyA,
	// keyB) was not known at all whereas err == ErrNotFound with
	// timestampmicro != 0 indicates (keyA, keyB) was known and had a deletion
	// marker (aka tombstone).
	Read(ctx context.Context, keyA uint64, keyB uint64, value []byte) (int64, []byte, error)
	// Write stores (timestampmicro, value) for (keyA, keyB) and returns the
	// previously stored timestampmicro or returns any error; a newer
	// timestampmicro already in place is not reported as an error. Note that
	// with a Write and a Delete for the exact same timestampmicro, the Delete
	// wins.
	Write(ctx context.Context, keyA uint64, keyB uint64, timestampmicro int64, value []byte) (int64, error)
	// Delete stores timestampmicro for (keyA, keyB) and returns the previously
	// stored timestampmicro or returns any error; a newer timestampmicro
	// already in place is not reported as an error. Note that with a Write and
	// a Delete for the exact same timestampmicro, the Delete wins.
	Delete(ctx context.Context, keyA uint64, keyB uint64, timestampmicro int64) (int64, error)
}

type ValueStoreConfig struct {
	// Scale sets how much to scale the default values by; this can reduce
	// memory usage for systems where the store isn't the only thing running on
	// the hardware. Note that this will *not* scale explictly set values, just
	// the values if they fallback to the defaults.
	Scale float64
	// Logger defines where log output will go. This library has minimal log
	// output (most meta data is sent via metrics) but some errors and debug
	// logging does exist. If not set, the logger will default to
	// zap.NewProduction()
	Logger *zap.Logger
	// LoggerName is used as a prefix when setting the "name" field with log
	// messages. For example, given a LoggerName of "mystoreapp", this library
	// would log under names such as "mystoreapp.compaction" and
	// "mystoreapp.recovery".
	LoggerName string
	// Rand sets the rand.Rand to use as a random data source. Defaults to a
	// new randomizer based on the current time.
	Rand *rand.Rand
	// Path sets the path where value files will be written; valuetoc files
	// will also be written here unless overridden with PathTOC. Defaults to
	// the current working directory.
	Path string
	// PathTOC sets the path where valuetoc files will be written. Defaults to
	// the Path value.
	PathTOC string
	// ValueCap indicates the maximum number of bytes any given value may be.
	// Defaults to 1,048,576 bytes.
	ValueCap int
	// Workers indicates how many goroutines may be used for various tasks
	// (processing incoming writes and batching them to disk, background tasks,
	// etc.). This will also have an impact on memory usage. Defaults to
	// GOMAXPROCS.
	Workers int
	// ChecksumInterval indicates how many bytes are output to a file before a
	// 4-byte checksum is also output. Defaults to 65,532 bytes.
	ChecksumInterval int
	// PageSize controls the size of each chunk of memory allocated. Defaults
	// to 4,194,304 bytes.
	PageSize int
	// WritePagesPerWorker controls how many pages are created per worker for
	// caching recently written values. Defaults to 3.
	WritePagesPerWorker int
	// ValueLocMap allows overriding the default ValueLocMap, an interface
	// used by ValueStore for tracking the mappings from keys to the locations
	// of their values. Defaults to
	// github.com/gholt/locmap.NewValueLocMap().
	ValueLocMap locmap.ValueLocMap
	// MsgRing sets the ring.MsgRing to use for determining the key ranges the
	// ValueStore is responsible for as well as providing methods to send
	// messages to other nodes.
	MsgRing msgring.MsgRing
	// MsgCap indicates the maximum bytes for outgoing messages. Defaults to
	// 16,777,216 bytes.
	MsgCap int
	// MsgTimeout indicates the maximum milliseconds a message can be pending
	// before just discarding it. Defaults to 250 milliseconds.
	MsgTimeout int
	// FileCap indicates how large a file can be before closing it and opening
	// a new one. Defaults to 4,294,967,295 bytes.
	FileCap int
	// FileReaders indicates how many open file descriptors are allowed per
	// file for reading. Defaults to Workers.
	FileReaders int
	// RecoveryBatchSize indicates how many keys to set in a batch while
	// performing recovery (initial start up). Defaults to 1,048,576 keys.
	RecoveryBatchSize int
	// TombstoneDiscardInterval indicates the minimum number of seconds between
	// the starts of background passes to discard expired tombstones [deletion
	// markers]. If set to 300 seconds and a pass takes 100 seconds to run, it
	// will wait 200 seconds (with a small amount of randomization) before
	// starting the next pass. Default: 300 seconds
	TombstoneDiscardInterval int
	// TombstoneDiscardBatchSize indicates how many items to queue up before
	// pausing a scan, issuing the actual discards, and resuming the scan
	// again. Defaults to 1,048,576 items.
	TombstoneDiscardBatchSize int
	// TombstoneAge indicates how many seconds old a deletion marker may be
	// before it is permanently removed. Defaults to 14,400 seconds (4 hours).
	TombstoneAge int
	// TombstoneDiscardWorkers indicates how many goroutines may be used for
	// discard passes (discarding expired tombstones [deletion markers]).
	// Defaults to 1 worker.
	TombstoneDiscardWorkers int
	// ReplicationIgnoreRecent indicates how many seconds old a value should be
	// before it is included in replication processing. Defaults to 60 seconds.
	ReplicationIgnoreRecent int
	// OutPullReplicationInterval is much like TombstoneDiscardInterval but for
	// outgoing pull replication passes. Default: 60 seconds
	OutPullReplicationInterval int
	// OutPullReplicationWorkers indicates how many goroutines may be used for
	// an outgoing pull replication pass. Defaults to Workers / 10 with a
	// minimum of 1.
	OutPullReplicationWorkers int
	// OutPullReplicationMsgs indicates how many outgoing pull-replication
	// messages can be buffered before blocking on creating more. Defaults to
	// OutPullReplicationWorkers * 4.
	OutPullReplicationMsgs int
	// OutPullReplicationBloomN indicates the N-factor for the outgoing
	// pull-replication bloom filters. This indicates how many keys the bloom
	// filter can reasonably hold and, in combination with the P-factor,
	// affects memory usage. Defaults to 1,000,000.
	OutPullReplicationBloomN int
	// OutPullReplicationBloomP indicates the P-factor for the outgoing
	// pull-replication bloom filters. This indicates the desired percentage
	// chance of a collision within the bloom filter and, in combination with
	// the N-factor, affects memory usage. Defaults to 0.001.
	OutPullReplicationBloomP float64
	// OutPullReplicationMsgTimeout indicates the maximum milliseconds an
	// outgoing pull replication message can be pending before just discarding
	// it. Defaults to MsgTimeout.
	OutPullReplicationMsgTimeout int
	// InPullReplicationWorkers indicates how many incoming pull-replication
	// messages can be processed at the same time. Defaults to Workers.
	InPullReplicationWorkers int
	// InPullReplicationMsgs indicates how many incoming pull-replication
	// messages can be buffered before dropping additional ones. Defaults to
	// InPullReplicationWorkers * 4.
	InPullReplicationMsgs int
	// InPullReplicationResponseMsgTimeout indicates the maximum milliseconds
	// an outgoing response message to an incoming pull replication message can
	// be pending before just discarding it. Defaults to MsgTimeout.
	InPullReplicationResponseMsgTimeout int
	// PushReplicationInterval is much like TombstoneDiscardInterval but for
	// outgoing push replication passes. Default: 60 seconds
	PushReplicationInterval int
	// PushReplicationWorkers indicates how many goroutines may be used for an
	// outgoing push replication pass. Defaults to Workers / 10 with minimum of
	// 1.
	PushReplicationWorkers int
	// PushReplicationMsgTimeout indicates the maximum milliseconds an
	// outgoing push replication message can be pending before just discarding
	// it. Defaults to MsgTimeout.
	PushReplicationMsgTimeout int
	// BulkSetMsgCap indicates the maximum bytes for bulk-set messages.
	// Defaults to MsgCap.
	BulkSetMsgCap int
	// OutBulkSetMsgs indicates how many outgoing bulk-set messages can be
	// buffered before blocking on creating more. Defaults to
	// PushReplicationWorkers * 4.
	OutBulkSetMsgs int
	// InBulkSetWorkers indicates how many incoming bulk-set messages can be
	// processed at the same time. Defaults to Workers.
	InBulkSetWorkers int
	// InBulkSetMsgs indicates how many incoming bulk-set messages can be
	// buffered before dropping additional ones. Defaults to InBulkSetWorkers *
	// 4.
	InBulkSetMsgs int
	// InBulkSetResponseMsgTimeout indicates the maximum milliseconds a
	// response message to an incoming bulk-set message can be pending before
	// just discarding it. Defaults to MsgTimeout.
	InBulkSetResponseMsgTimeout int
	// BulkSetAckMsgCap indicates the maximum bytes for bulk-set-ack messages.
	// Defaults to MsgCap.
	BulkSetAckMsgCap int
	// InBulkSetAckWorkers indicates how many incoming bulk-set-ack messages
	// can be processed at the same time. Defaults to Workers.
	InBulkSetAckWorkers int
	// InBulkSetAckMsgs indicates how many incoming bulk-set-ack messages can
	// be buffered before dropping additional ones. Defaults to
	// InBulkSetAckWorkers * 4.
	InBulkSetAckMsgs int
	// OutBulkSetAckMsgs indicates how many outgoing bulk-set-ack messages can
	// be buffered before blocking on creating more. Defaults to
	// InBulkSetWorkers * 4.
	OutBulkSetAckMsgs int
	// CompactionInterval is much like TombstoneDiscardInterval but for
	// compaction passes. Default: 600 seconds
	CompactionInterval int
	// CompactionWorkers indicates how much concurrency is allowed for
	// compaction. Defaults to 1.
	CompactionWorkers int
	// CompactionThreshold indicates how much waste a given file may have
	// before it is compacted. Defaults to 0.10 (10%).
	CompactionThreshold float64
	// CompactionAgeThreshold indicates how old a given file must be before it
	// is considered for compaction. Defaults to 300 seconds.
	CompactionAgeThreshold int
	// DiskFreeDisableThreshold controls when to automatically disable writes;
	// the number is in bytes. If the number of free bytes on either the Path
	// or TOCPath device falls below this threshold, writes will be
	// automatically disabled.
	// 0 will use the default; 1 will disable the check.
	// default: 8,589,934,592 (8G)
	DiskFreeDisableThreshold uint64
	// DiskFreeReenableThreshold controls when to automatically re-enable
	// writes; the number is in bytes. If writes are automatically disabled and
	// the number of free bytes on each of the Path or TOCPath devices rises
	// above this threshold, writes will be automatically re-enabled. A
	// negative value will turn off this check.
	// 0 will use the default; 1 will disable the check.
	// default: 17,179,869,184 (16G)
	DiskFreeReenableThreshold uint64
	// DiskUsageDisableThreshold controls when to automatically disable writes;
	// the number is a percentage (1 == 100%). If the percentage used on either
	// the Path or TOCPath device grows above this threshold, writes will be
	// automatically disabled.
	// 0 will use the default; a negative value will disable the check.
	// default: 0.94 (94%)
	DiskUsageDisableThreshold float64
	// DiskUsageReenableThreshold controls when to automatically re-enable
	// writes; the number is a percentage (1 == 100%). If writes are
	// automatically disabled and the percentage used on each of the Path or
	// TOCPath devices falls below this threshold, writes will be automatically
	// re-enabled.
	// 0 will use the default; a negative value will disable the check.
	// default: 0.90 (90%)
	DiskUsageReenableThreshold float64
	// FlusherThreshold sets the number of to-disk modifications controlling
	// the once-a-minute automatic flusher. If there are less than this
	// setting's number of modifications for a minute, the store's Flush method
	// will be called. This is so relatively idle stores won't just leave the
	// last few modifications sitting only in memory for too long, but without
	// penalizing active stores that will already be sending recent
	// modifications to disk as ever more recent modifications occur.
	// 0 will use the default; a negative value will disable the check.
	// default is the number of entries that are guaranteed to fill a memory
	// page; this depends on the PageSize value and the internal struct size
	// for the store.
	FlusherThreshold int32
	// AuditInterval is much like TombstoneDiscardInterval but for audit
	// passes. Default: 604,800 seconds (1 week).
	AuditInterval int
	// AuditAgeThreshold indicates how old a given file must be before it
	// is considered for an audit. Defaults to 604,800 seconds (1 week).
	AuditAgeThreshold int
	// MemFreeDisableThreshold controls when to automatically disable writes;
	// the number is in bytes. If the number of free bytes of memory falls
	// below this threshold, writes will be automatically disabled.
	// 0 will use the default; 1 will disable the check.
	// default: 134,217,728 (128M)
	MemFreeDisableThreshold uint64
	// MemFreeReenableThreshold controls when to automatically re-enable
	// writes; the number is in bytes. If writes are automatically disabled and
	// the number of free bytes of memory rises above this threshold, writes
	// will be automatically re-enabled. A negative value will turn off this
	// check.
	// 0 will use the default; 1 will disable the check.
	// default: 268,435,456 (256M)
	MemFreeReenableThreshold uint64
	// MemUsageDisableThreshold controls when to automatically disable writes;
	// the number is a percentage (1 == 100%). If the percentage of used memory
	// grows above this threshold, writes will be automatically disabled.
	// 0 will use the default; a negative value will disable the check.
	// default: 0.94 (94%)
	MemUsageDisableThreshold float64
	// MemUsageReenableThreshold controls when to automatically re-enable
	// writes; the number is a percentage (1 == 100%). If writes are
	// automatically disabled and the percentage of used memory falls below
	// this threshold, writes will be automatically re-enabled.
	// 0 will use the default; a negative value will disable the check.
	// default: 0.90 (90%)
	MemUsageReenableThreshold float64
	// contains filtered or unexported fields
}

type ValueStoreStats struct {
	// Values is the number of values in the ValueStore.
	Values uint64
	// ValuesBytes is the number of bytes of the values in the ValueStore.
	ValueBytes uint64
	// Lookups is the number of calls to Lookup.
	Lookups int32
	// LookupErrors is the number of errors returned by Lookup; not-found
	// errors do not count here.
	LookupErrors int32

	// Reads is the number of calls to Read.
	Reads int32
	// ReadErrors is the number of errors returned by Read; not-found errors do
	// not count here.
	ReadErrors int32

	// Writes is the number of calls to Write.
	Writes int32
	// WriteErrors is the number of errors returned by Write.
	WriteErrors int32
	// WritesOverridden is the number of calls to Write that resulted in no
	// change.
	WritesOverridden int32
	// Deletes is the number of calls to Delete.
	Deletes int32
	// DeleteErrors is the number of errors returned by Delete.
	DeleteErrors int32
	// DeletesOverridden is the number of calls to Delete that resulted in no
	// change.
	DeletesOverridden int32
	// OutBulkSets is the number of outgoing bulk-set messages in response to
	// incoming pull replication messages.
	OutBulkSets int32
	// OutBulkSetValues is the number of values in outgoing bulk-set messages;
	// these bulk-set messages are those in response to incoming
	// pull-replication messages.
	OutBulkSetValues int32
	// OutBulkSetPushes is the number of outgoing bulk-set messages due to push
	// replication.
	OutBulkSetPushes int32
	// OutBulkSetPushValues is the number of values in outgoing bulk-set
	// messages; these bulk-set messages are those due to push replication.
	OutBulkSetPushValues int32
	// OutPushReplicationNanoseconds is how long the last out push replication
	// pass took.
	OutPushReplicationNanoseconds int64
	// InBulkSets is the number of incoming bulk-set messages.
	InBulkSets int32
	// InBulkSetDrops is the number of incoming bulk-set messages dropped due
	// to the local system being overworked at the time.
	InBulkSetDrops int32
	// InBulkSetInvalids is the number of incoming bulk-set messages that
	// couldn't be parsed.
	InBulkSetInvalids int32
	// InBulkSetWrites is the number of writes due to incoming bulk-set
	// messages.
	InBulkSetWrites int32
	// InBulkSetWriteErrors is the number of errors returned from writes due to
	// incoming bulk-set messages.
	InBulkSetWriteErrors int32
	// InBulkSetWritesOverridden is the number of writes from incoming bulk-set
	// messages that result in no change.
	InBulkSetWritesOverridden int32
	// OutBulkSetAcks is the number of outgoing bulk-set-ack messages.
	OutBulkSetAcks int32
	// InBulkSetAcks is the number of incoming bulk-set-ack messages.
	InBulkSetAcks int32
	// InBulkSetAckDrops is the number of incoming bulk-set-ack messages
	// dropped due to the local system being overworked at the time.
	InBulkSetAckDrops int32
	// InBulkSetAckInvalids is the number of incoming bulk-set-ack messages
	// that couldn't be parsed.
	InBulkSetAckInvalids int32
	// InBulkSetAckWrites is the number of writes (for local removal) due to
	// incoming bulk-set-ack messages.
	InBulkSetAckWrites int32
	// InBulkSetAckWriteErrors is the number of errors returned from writes due
	// to incoming bulk-set-ack messages.
	InBulkSetAckWriteErrors int32
	// InBulkSetAckWritesOverridden is the number of writes from incoming
	// bulk-set-ack messages that result in no change.
	InBulkSetAckWritesOverridden int32
	// OutPullReplications is the number of outgoing pull-replication messages.
	OutPullReplications int32
	// OutPullReplicationNanoseconds is how long the last out pull replication
	// pass took.
	OutPullReplicationNanoseconds int64
	// InPullReplications is the number of incoming pull-replication messages.
	InPullReplications int32
	// InPullReplicationDrops is the number of incoming pull-replication
	// messages droppped due to the local system being overworked at the time.
	InPullReplicationDrops int32
	// InPullReplicationInvalids is the number of incoming pull-replication
	// messages that couldn't be parsed.
	InPullReplicationInvalids int32
	// ExpiredDeletions is the number of recent deletes that have become old
	// enough to be completely discarded.
	ExpiredDeletions int32
	// TombstoneDiscardNanoseconds is how long the last tombstone discard pass
	// took.
	TombstoneDiscardNanoseconds int64
	// CompactionNanoseconds is how long the last compaction pass took.
	CompactionNanoseconds int64
	// Compactions is the number of disk file sets compacted due to their
	// contents exceeding a staleness threshold. For example, this happens when
	// enough of the values have been overwritten or deleted in more recent
	// operations.
	Compactions int32
	// SmallFileCompactions is the number of disk file sets compacted due to
	// the entire file size being too small. For example, this may happen when
	// the store is shutdown and restarted.
	SmallFileCompactions int32
	// DiskFree is the number of bytes free on the device containing the
	// Config.Path for the defaultValueStore.
	DiskFree uint64
	// DiskUsed is the number of bytes used on the device containing the
	// Config.Path for the defaultValueStore.
	DiskUsed uint64
	// DiskSize is the size in bytes of the device containing the Config.Path
	// for the defaultValueStore.
	DiskSize uint64
	// DiskFreeTOC is the number of bytes free on the device containing the
	// Config.PathTOC for the defaultValueStore.
	DiskFreeTOC uint64
	// DiskUsedTOC is the number of bytes used on the device containing the
	// Config.PathTOC for the defaultValueStore.
	DiskUsedTOC uint64
	// DiskSizeTOC is the size in bytes of the device containing the
	// Config.PathTOC for the defaultValueStore.
	DiskSizeTOC uint64
	// MemFree is the number of bytes of free memory.
	MemFree uint64
	// MemUsed is the number of bytes of used memory.
	MemUsed uint64
	// MemSize is the size in bytes of total memory on the system.
	MemSize uint64
	// ReadOnly indicates when the system has been put in read-only mode,
	// whether by DisableWrites or automatically by the watcher.
	ReadOnly bool
	// AuditNanoseconds is how long the last audit pass took.
	AuditNanoseconds int64
	// contains filtered or unexported fields
}