github.com/grailbio/bigslice@v0.0.0-20230519005545-30c4c12152ad/frame/codec.go (about)

     1  // Copyright 2018 GRAIL, Inc. All rights reserved.
     2  // Use of this source code is governed by the Apache 2.0
     3  // license that can be found in the LICENSE file.
     4  
     5  package frame
     6  
     7  import "sync/atomic"
     8  
     9  // Key represents a key that can be used to store session specific
    10  // state.
    11  type Key uint64
    12  
    13  // Session is a key-value store that is used by frame codecs to
    14  // store session-specific state.
    15  type Session interface {
    16  	// State retrieves the session state for the provided key
    17  	// into the pointer state. If state is not a pointer, then
    18  	// State will panic. State returns true the first time the key
    19  	// is encountered in the session. This is typically used by
    20  	// user code to initialize the state.
    21  	//
    22  	// If the state value is a pointer, then the first call to State
    23  	// sets the state pointer (a pointer to a pointer) to a newly
    24  	// allocated value. Otherwise it is set to a zero value of the
    25  	// value type.
    26  	State(key Key, state interface{}) bool
    27  }
    28  
    29  // An Encoder manages transmission of data over a connection or file.
    30  type Encoder interface {
    31  	Session
    32  	// Encode encodes the provided value into the
    33  	// encoder's stream using Gob.
    34  	Encode(v interface{}) error
    35  }
    36  
    37  type Decoder interface {
    38  	Session
    39  	// Decode decodes a value from the underlying stream using
    40  	// Gob.
    41  	Decode(v interface{}) error
    42  }
    43  
    44  var key uint64
    45  
    46  // FreshKey returns a unique key that can be used to store
    47  // state in sessions.
    48  func FreshKey() Key {
    49  	return Key(atomic.AddUint64(&key, 1))
    50  }