runtime

package
v0.0.0-...-a134451 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 28, 2024 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// APIVersionInternal may be used if you are registering a type that should not
	// be considered stable or serialized - it is a convention only and has no
	// special behavior in this package.
	APIVersionInternal = "v1"
)
View Source 
const (
	ContentTypeJSON string = "application/json"
)

Variables

View Source 
var AllocatorPool = sync.Pool{
	New: func() interface{} {
		return &Allocator{}
	},
}

AllocatorPool simply stores Allocator objects to avoid additional memory allocations by caching created but unused items for later reuse, relieving pressure on the garbage collector.

Usage: 

memoryAllocator := runtime.AllocatorPool.Get().(*runtime.Allocator)
defer runtime.AllocatorPool.Put(memoryAllocator)

A note for future: 

consider introducing multiple pools for storing buffers of different sizes
perhaps this could allow us to be more efficient.
View Source 
var ErrorHandlers = []func(error){
	logError,
	(&rudimentaryErrorBackoff{
		lastErrorTime: time.Now(),

		minPeriod: time.Millisecond,
	}).OnError,
}

ErrorHandlers is a list of functions which will be invoked when a nonreturnable error occurs.

Functions

func DecodeInto 

func DecodeInto(d Decoder, data []byte, into Object) error

DecodeInto performs a Decode into the provided object.

func Encode 

func Encode(e Encoder, obj Object) ([]byte, error)

Encode is a convenience wrapper for encoding to a []byte from an Encoder

func EnforcePtr 

func EnforcePtr(obj interface{}) (reflect.Value, error)

EnforcePtr ensures that obj is a pointer of some sort. Returns a reflect.Value of the dereferenced pointer, ensuring that it is settable/addressable. Returns an error if this is not possible.

func GetItemsPtr 

func GetItemsPtr(list Object) (interface{}, error)

GetItemsPtr returns a pointer to the list object's Items member. If 'list' doesn't have an Items member, it's not really a list type and an error will be returned. This function will either return a pointer to a slice, or an error, but not both.

func HandleError 

func HandleError(err error)

HandleError is a method to invoke when a non-user facing piece of code cannot return an error and needs to indicate it has been ignored. Invoking this method is preferable to logging the error - the default behavior is to log but the errors may be sent to a remote server for analysis.

Types

type Allocator 

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

Allocator knows how to allocate memory It exists to make the cost of object serialization cheaper. In some cases, it allows for allocating memory only once and then reusing it. This approach puts less load on GC and leads to less fragmented memory in general.

func (*Allocator) Allocate 

func (a *Allocator) Allocate(n uint64) []byte

Allocate reserves memory for n bytes only if the underlying array doesn't have enough capacity otherwise it returns previously allocated block of memory.

Note that the returned array is not zeroed, it is the caller's responsibility to clean the memory if needed.

type ClientNegotiator 

type ClientNegotiator interface {
	// Encoder returns the appropriate encoder for the provided contentType (e.g. application/json)
	// and any optional mediaType parameters (e.g. pretty=1), or an error. If no serializer is found
	// a NegotiateError will be returned. The current client implementations consider params to be
	// optional modifiers to the contentType and will ignore unrecognized parameters.
	Encoder(contentType string, params map[string]string) (Encoder, error)
	// Decoder returns the appropriate decoder for the provided contentType (e.g. application/json)
	// and any optional mediaType parameters (e.g. pretty=1), or an error. If no serializer is found
	// a NegotiateError will be returned. The current client implementations consider params to be
	// optional modifiers to the contentType and will ignore unrecognized parameters.
	Decoder(contentType string, params map[string]string) (Decoder, error)
	// StreamDecoder returns the appropriate stream decoder for the provided contentType (e.g.
	// application/json) and any optional mediaType parameters (e.g. pretty=1), or an error. If no
	// serializer is found a NegotiateError will be returned. The Serializer and Framer will always
	// be returned if a Decoder is returned. The current client implementations consider params to be
	// optional modifiers to the contentType and will ignore unrecognized parameters.
	StreamDecoder(contentType string, params map[string]string) (Decoder, Serializer, Framer, error)
}

ClientNegotiator handles turning an HTTP content type into the appropriate encoder. Use NewClientNegotiator or NewVersionedClientNegotiator to create this interface from a NegotiatedSerializer.

func NewClientNegotiator 

func NewClientNegotiator(serializer NegotiatedSerializer, gv schema.GroupVersion) ClientNegotiator

NewClientNegotiator will attempt to retrieve the appropriate encoder, decoder, or stream decoder for a given content type. Does not perform any conversion, but will encode the object to the desired group, version, and kind. Use when creating a client.

type Codec 

type Codec Serializer

Codec is a Serializer that deals with the details of versioning objects. It offers the same interface as Serializer, so this is a marker to consumers that care about the version of the objects they receive.

func NewCodec 

func NewCodec(e Encoder, d Decoder) Codec

NewCodec creates a Codec from an Encoder and Decoder.

type Decoder 

type Decoder interface {
	// Decode attempts to deserialize the provided data using either the innate typing of the scheme or the
	// default kind, group, and version provided. It returns a decoded object as well as the kind, group, and
	// version from the serialized data, or an error. If into is non-nil, it will be used as the target type
	// and implementations may choose to use it rather than reallocating an object. However, the object is not
	// guaranteed to be populated. The returned object is not guaranteed to match into. If defaults are
	// provided, they are applied to the data by default. If no defaults or partial defaults are provided, the
	// type of the into may be used to guide conversion decisions.
	Decode(data []byte, defaults *schema.GroupVersionKind, into Object) (Object, *schema.GroupVersionKind, error)
}

Decoder attempts to load an object from data.

type Encoder 

type Encoder interface {
	// Encode writes an object to a stream. Implementations may return errors if the versions are
	// incompatible, or if no conversion is defined.
	Encode(obj Object, w io.Writer) error
	// Identifier returns an identifier of the encoder.
	// Identifiers of two different encoders should be equal if and only if for every input
	// object it will be encoded to the same representation by both of them.
	//
	// Identifier is intended for use with CacheableObject#CacheEncode method. In order to
	// correctly handle CacheableObject, Encode() method should look similar to below, where
	// doEncode() is the encoding logic of implemented encoder:
	//   func (e *MyEncoder) Encode(obj Object, w io.Writer) error {
	//     if co, ok := obj.(CacheableObject); ok {
	//       return co.CacheEncode(e.Identifier(), e.doEncode, w)
	//     }
	//     return e.doEncode(obj, w)
	//   }
	Identifier() Identifier
}

Encoder writes objects to a serialized form

type EncoderWithAllocator 

type EncoderWithAllocator interface {
	Encoder
	// EncodeWithAllocator writes an object to a stream as Encode does.
	// In addition, it allows for providing a memory allocator for efficient memory usage during object serialization
	EncodeWithAllocator(obj Object, w io.Writer, memAlloc MemoryAllocator) error
}

EncoderWithAllocator serializes objects in a way that allows callers to manage any additional memory allocations.

type FieldLabelConversionFunc 

type FieldLabelConversionFunc func(label, value string) (internalLabel, internalValue string, err error)

FieldLabelConversionFunc converts a field selector to internal representation.

type Framer 

type Framer interface {
	NewFrameReader(r io.ReadCloser) io.ReadCloser
	NewFrameWriter(w io.Writer) io.Writer
}

Framer is a factory for creating readers and writers that obey a particular framing pattern.

type GroupVersioner 

type GroupVersioner interface {
	// KindForGroupVersionKinds returns a desired target group version kind for the given input, or returns ok false if no
	// target is known. In general, if the return target is not in the input list, the caller is expected to invoke
	// Scheme.New(target) and then perform a conversion between the current Go type and the destination Go type.
	// Sophisticated implementations may use additional information about the input kinds to pick a destination kind.
	KindForGroupVersionKinds(kinds []schema.GroupVersionKind) (target schema.GroupVersionKind, ok bool)
	// Identifier returns string representation of the object.
	// Identifiers of two different encoders should be equal only if for every input
	// kinds they return the same result.
	Identifier() string
}

GroupVersioner refines a set of possible conversion targets into a single option.

type Identifier 

type Identifier string

Identifier represents an identifier. Identitier of two different objects should be equal if and only if for every input the output they produce is exactly the same.

type MemoryAllocator 

type MemoryAllocator interface {
	// Allocate reserves memory for n bytes.
	// Note that implementations of this method are not required to zero the returned array.
	// It is the caller's responsibility to clean the memory if needed.
	Allocate(n uint64) []byte
}

MemoryAllocator is responsible for allocating memory. By encapsulating memory allocation into its own interface, we can reuse the memory across many operations in places we know it can significantly improve the performance.

type NegotiateError 

type NegotiateError struct {
	ContentType string
	Stream      bool
}

NegotiateError is returned when a ClientNegotiator is unable to locate a serializer for the requested operation.

func (NegotiateError) Error 

func (e NegotiateError) Error() string

type NegotiatedSerializer 

type NegotiatedSerializer interface {
	// SupportedMediaTypes is the media types supported for reading and writing single objects.
	SupportedMediaTypes() []SerializerInfo

	// EncoderForVersion returns an encoder that ensures objects being written to the provided
	// serializer are in the provided group version.
	EncoderForVersion(serializer Encoder, gv GroupVersioner) Encoder
	// DecoderToVersion returns a decoder that ensures objects being read by the provided
	// serializer are in the provided group version by default.
	DecoderToVersion(serializer Decoder, gv GroupVersioner) Decoder
}

NegotiatedSerializer is an interface used for obtaining encoders, decoders, and serializers for multiple supported media types. This would commonly be accepted by a server component that performs HTTP content negotiation to accept multiple formats.

type Object 

type Object interface {
	GetObjectKind() schema.ObjectKind
	DeepCopyObject() Object
}

Object interface must be supported by all API types registered with Scheme. Since objects in a scheme are expected to be serialized to the wire, the interface an Object must provide to the Scheme allows serializers to set the kind, version, and group the object is represented as. An Object may choose to return a no-op ObjectKindAccessor in cases where it is not expected to be serialized.

func Decode 

func Decode(d Decoder, data []byte, obj Object) (Object, error)

Decode is a convenience wrapper for decoding data into an Object.

type ObjectTyper 

type ObjectTyper interface {
	// ObjectKinds returns the all possible group,version,kind of the provided object, true if
	// the object is unversioned, or an error if the object is not recognized
	// (IsNotRegisteredError will return true).
	ObjectKinds(Object) ([]schema.GroupVersionKind, bool, error)
	// Recognizes returns true if the scheme is able to handle the provided version and kind,
	// or more precisely that the provided version is a possible conversion or decoding
	// target.
	Recognizes(gvk schema.GroupVersionKind) bool
}

ObjectTyper contains methods for extracting the APIVersion and Kind of objects.

type ParameterCodec 

type ParameterCodec interface {
	// DecodeParameters takes the given url.Values in the specified group version and decodes them
	// into the provided object, or returns an error.
	DecodeParameters(parameters url.Values, from schema.GroupVersion, into Object) error
	// EncodeParameters encodes the provided object as query parameters or returns an error.
	EncodeParameters(obj Object, to schema.GroupVersion) (url.Values, error)
}

ParameterCodec defines methods for serializing and deserializing API objects to url.Values and performing any necessary conversion. Unlike the normal Codec, query parameters are not self describing and the desired version must be specified.

type Scheme 

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

Scheme defines methods for serializing and deserializing API objects, a type registry for converting group, version, and kind information to and from Go schemas, and mappings between Go schemas of different versions. A scheme is the foundation for a versioned API and versioned configuration over time.

In a Scheme, a Type is a particular Go struct, a Version is a point-in-time identifier for a particular representation of that Type (typically backwards compatible), a Kind is the unique name for that Type within the Version, and a Group identifies a set of Versions, Kinds, and Types that evolve over time. An Unversioned Type is one that is not yet formally bound to a type and is promised to be backwards compatible (effectively a "v1" of a Type that does not expect to break in the future).

Schemes are not expected to change at runtime and are only threadsafe after registration is complete.

func NewScheme 

func NewScheme() *Scheme

NewScheme creates a new Scheme. This scheme is pluggable by default.

func (*Scheme) AddGeneratedConversionFunc 

func (s *Scheme) AddGeneratedConversionFunc(a, b interface{}, fn interface{}) error

AddGeneratedConversionFunc registers a function that converts between a and b by passing objects of those types to the provided function. The function *must* accept objects of a and b - this machinery will not enforce any other guarantee.

func (*Scheme) AddKnownTypeWithName 

func (s *Scheme) AddKnownTypeWithName(gvk schema.GroupVersionKind, obj Object)

AddKnownTypeWithName is like AddKnownTypes, but it lets you specify what this type should be encoded as. Useful for testing when you don't want to make multiple packages to define your structs. Version may not be empty - use the APIVersionInternal constant if you have a type that does not have a formal version.

func (*Scheme) AddKnownTypes 

func (s *Scheme) AddKnownTypes(gv schema.GroupVersion, types ...Object)

AddKnownTypes registers all types passed in 'types' as being members of version 'version'. All objects passed to types should be pointers to structs. The name that go reports for the struct becomes the "kind" field when encoding. Version may not be empty - use the APIVersionInternal constant if you have a type that does not have a formal version.

func (*Scheme) Name 

func (s *Scheme) Name() string

func (*Scheme) ObjectKinds 

func (s *Scheme) ObjectKinds(obj Object) ([]schema.GroupVersionKind, bool, error)

ObjectKinds returns all possible group,version,kind of the go object, true if the object is considered unversioned, or an error if it's not a pointer or is unregistered.

func (*Scheme) Recognizes 

func (s *Scheme) Recognizes(gvk schema.GroupVersionKind) bool

Recognizes returns true if the scheme is able to handle the provided group,version,kind of object.

type SchemeBuilder 

type SchemeBuilder []func(*Scheme) error

SchemeBuilder collects functions that add things to a scheme. It's to allow code to compile without explicitly referencing generated types. You should declare one in each package that will have generated deep copy or conversion functions.

func NewSchemeBuilder 

func NewSchemeBuilder(funcs ...func(*Scheme) error) SchemeBuilder

NewSchemeBuilder calls Register for you.

func (*SchemeBuilder) AddToScheme 

func (sb *SchemeBuilder) AddToScheme(s *Scheme) error

AddToScheme applies all the stored functions to the scheme. A non-nil error indicates that one function failed and the attempt was abandoned.

func (*SchemeBuilder) Register 

func (sb *SchemeBuilder) Register(funcs ...func(*Scheme) error)

Register adds a scheme setup function to the list.

type Serializer 

type Serializer interface {
	Encoder
	Decoder
}

Serializer is the core interface for transforming objects into a serialized format and back. Implementations may choose to perform conversion of the object, but no assumptions should be made.

type SerializerInfo 

type SerializerInfo struct {
	// MediaType is the value that represents this serializer over the wire.
	MediaType string
	// MediaTypeType is the first part of the MediaType ("application" in "application/json").
	MediaTypeType string
	// MediaTypeSubType is the second part of the MediaType ("json" in "application/json").
	MediaTypeSubType string
	// EncodesAsText indicates this serializer can be encoded to UTF-8 safely.
	EncodesAsText bool
	// Serializer is the individual object serializer for this media type.
	Serializer Serializer
	// PrettySerializer, if set, can serialize this object in a form biased towards
	// readability.
	PrettySerializer Serializer
	// StrictSerializer, if set, deserializes this object strictly,
	// erring on unknown fields.
	StrictSerializer Serializer
	// StreamSerializer, if set, describes the streaming serialization format
	// for this media type.
	StreamSerializer *StreamSerializerInfo
}

SerializerInfo contains information about a specific serialization format

func SerializerInfoForMediaType 

func SerializerInfoForMediaType(types []SerializerInfo, mediaType string) (SerializerInfo, bool)

SerializerInfoForMediaType returns the first info in types that has a matching media type (which cannot include media-type parameters), or the first info with an empty media type, or false if no type matches.

type SimpleAllocator 

type SimpleAllocator struct{}

SimpleAllocator a wrapper around make([]byte) conforms to the MemoryAllocator interface

func (*SimpleAllocator) Allocate 

func (sa *SimpleAllocator) Allocate(n uint64) []byte

type StreamSerializerInfo 

type StreamSerializerInfo struct {
	// EncodesAsText indicates this serializer can be encoded to UTF-8 safely.
	EncodesAsText bool
	// Serializer is the top level object serializer for this type when streaming
	Serializer
	// Framer is the factory for retrieving streams that separate objects on the wire
	Framer
}

StreamSerializerInfo contains information about a specific stream serialization format

type Unstructured 

type Unstructured interface {
	Object
	// NewEmptyInstance returns a new instance of the concrete type containing only kind/apiVersion and no other data.
	// This should be called instead of reflect.New() for unstructured types because the go type alone does not preserve kind/apiVersion info.
	NewEmptyInstance() Unstructured
	// UnstructuredContent returns a non-nil map with this object's contents. Values may be
	// []interface{}, map[string]interface{}, or any primitive type. Contents are typically serialized to
	// and from JSON. SetUnstructuredContent should be used to mutate the contents.
	UnstructuredContent() map[string]interface{}
	// SetUnstructuredContent updates the object content to match the provided map.
	SetUnstructuredContent(map[string]interface{})
	// IsList returns true if this type is a list or matches the list convention - has an array called "items".
	IsList() bool
	// EachListItem should pass a single item out of the list as an Object to the provided function. Any
	// error should terminate the iteration. If IsList() returns false, this method should return an error
	// instead of calling the provided function.
	EachListItem(func(Object) error) error
}

Unstructured objects store values as map[string]interface{}, with only values that can be serialized to JSON allowed.

Source Files

View all Source files

Directories

Path Synopsis
serializer
json
streaming

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.