context

type Cancellable interface {
	// IsCancelled determines whether the object is cancelled.
	IsCancelled() bool

	// Cancel cancels the object.
	Cancel()

	// Reset resets the object.
	Reset()
}

type Context interface {
	// IsClosed returns whether the context is closed.
	IsClosed() bool

	// RegisterFinalizer will register a resource finalizer.
	RegisterFinalizer(resource.Finalizer)

	// RegisterCloser will register a resource closer.
	RegisterCloser(resource.Closer)

	// DependsOn will register a blocking context that
	// must complete first before finalizers can be called.
	DependsOn(Context)

	// Close will close the context.
	Close()

	// BlockingClose will close the context and call the
	// registered finalizers in a blocking manner after waiting
	// for any dependent contexts to close. After calling
	// the context becomes safe to reset and reuse again
	// if and only if it is not a pooled context.
	BlockingClose()

	// Reset will reset the context for reuse.
	Reset()

	// BlockingCloseReset will close the context and call the
	// registered finalizers in a blocking manner after waiting
	// for any dependent contexts to close. After calling
	// the context becomes reset and is safe for reuse again as it
	// will not be returned to a pool.
	BlockingCloseReset()

	// GoContext returns the Go std context.
	GoContext() (stdctx.Context, bool)

	// SetGoContext sets the Go std context.
	SetGoContext(stdctx.Context)

	// StartTraceSpan starts a new span and returns a child ctx.
	StartTraceSpan(string) (Context, opentracing.Span)

	// StartSampledTraceSpan starts a new span and returns a child ctx
	// and a bool if the span is being sampled. This is used over StartTraceSpan()
	// for hot paths where performance is crucial.
	StartSampledTraceSpan(string) (Context, opentracing.Span, bool)
}

type Options interface {
	// SetContextPoolOptions sets the context pool options.
	SetContextPoolOptions(pool.ObjectPoolOptions) Options

	// ContextPoolOptions returns the context pool options.
	ContextPoolOptions() pool.ObjectPoolOptions

	// SetFinalizerPoolOptions sets the finalizer pool options.
	SetFinalizerPoolOptions(pool.ObjectPoolOptions) Options

	// FinalizerPoolOptions returns the finalizer pool options.
	FinalizerPoolOptions() pool.ObjectPoolOptions
}

type Pool interface {
	// Get provides a context from the pool.
	Get() Context

	// Put returns a context to the pool.
	Put(Context)
}