github.com/m3db/m3@v1.5.1-0.20231129193456-75a402aa583b/src/x/context/types.go (about)

     1  // Copyright (c) 2018 Uber Technologies, Inc.
     2  //
     3  // Permission is hereby granted, free of charge, to any person obtaining a copy
     4  // of this software and associated documentation files (the "Software"), to deal
     5  // in the Software without restriction, including without limitation the rights
     6  // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
     7  // copies of the Software, and to permit persons to whom the Software is
     8  // furnished to do so, subject to the following conditions:
     9  //
    10  // The above copyright notice and this permission notice shall be included in
    11  // all copies or substantial portions of the Software.
    12  //
    13  // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    14  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    15  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    16  // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    17  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    18  // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
    19  // THE SOFTWARE.
    20  
    21  package context
    22  
    23  import (
    24  	stdctx "context"
    25  
    26  	"github.com/m3db/m3/src/x/pool"
    27  	xresource "github.com/m3db/m3/src/x/resource"
    28  
    29  	"github.com/opentracing/opentracing-go"
    30  )
    31  
    32  // Cancellable is an object that can be cancelled.
    33  type Cancellable interface {
    34  	// IsCancelled determines whether the object is cancelled.
    35  	IsCancelled() bool
    36  
    37  	// Cancel cancels the object.
    38  	Cancel()
    39  
    40  	// Reset resets the object.
    41  	Reset()
    42  }
    43  
    44  // Context provides context to an operation.
    45  type Context interface {
    46  	// IsClosed returns whether the context is closed.
    47  	IsClosed() bool
    48  
    49  	// RegisterFinalizer will register a resource finalizer.
    50  	RegisterFinalizer(xresource.Finalizer)
    51  
    52  	// RegisterCloser will register a resource closer.
    53  	RegisterCloser(xresource.SimpleCloser)
    54  
    55  	// DependsOn will register a blocking context that
    56  	// must complete first before finalizers can be called.
    57  	DependsOn(Context)
    58  
    59  	// Close will close the context.
    60  	Close()
    61  
    62  	// BlockingClose will close the context and call the
    63  	// registered finalizers in a blocking manner after waiting
    64  	// for any dependent contexts to close. After calling
    65  	// the context becomes safe to reset and reuse again
    66  	// if and only if it is not a pooled context.
    67  	BlockingClose()
    68  
    69  	// Reset will reset the context for reuse.
    70  	Reset()
    71  
    72  	// BlockingCloseReset will close the context and call the
    73  	// registered finalizers in a blocking manner after waiting
    74  	// for any dependent contexts to close. After calling
    75  	// the context becomes reset and is safe for reuse again as it
    76  	// will not be returned to a pool.
    77  	BlockingCloseReset()
    78  
    79  	// GoContext returns the std go context.
    80  	GoContext() stdctx.Context
    81  
    82  	// SetGoContext sets the Go std context.
    83  	SetGoContext(stdctx.Context)
    84  
    85  	// StartTraceSpan starts a new span and returns a child ctx.
    86  	StartTraceSpan(string) (Context, opentracing.Span)
    87  
    88  	// StartSampledTraceSpan starts a new span and returns a child ctx
    89  	// and a bool if the span is being sampled. This is used over StartTraceSpan()
    90  	// for hot paths where performance is crucial.
    91  	StartSampledTraceSpan(string) (Context, opentracing.Span, bool)
    92  
    93  	// DistanceFromRootContext returns the distance from root context (root context tree)
    94  	DistanceFromRootContext() uint16
    95  }
    96  
    97  // Pool provides a pool for contexts.
    98  type Pool interface {
    99  	// Get provides a context from the pool.
   100  	Get() Context
   101  
   102  	// Put returns a context to the pool.
   103  	Put(Context)
   104  }
   105  
   106  // Options controls knobs for context pooling.
   107  type Options interface {
   108  	// SetContextPoolOptions sets the context pool options.
   109  	SetContextPoolOptions(pool.ObjectPoolOptions) Options
   110  
   111  	// ContextPoolOptions returns the context pool options.
   112  	ContextPoolOptions() pool.ObjectPoolOptions
   113  
   114  	// SetFinalizerPoolOptions sets the finalizer pool options.
   115  	SetFinalizerPoolOptions(pool.ObjectPoolOptions) Options
   116  
   117  	// FinalizerPoolOptions returns the finalizer pool options.
   118  	FinalizerPoolOptions() pool.ObjectPoolOptions
   119  }
   120  
   121  // contextPool is the internal pool interface for contexts.
   122  type contextPool interface {
   123  	Pool
   124  	getFinalizeablesList() *finalizeableList
   125  	putFinalizeablesList(v *finalizeableList)
   126  }