types

Documentation

Overview

Package types contains the infrastructure needed to support serialization of Go types.

Index

• Variables
• func Deserialize(b []byte) (interface{}, []byte, error)
• func DeserializeTo[T any](d *Deserializer, x *T)
• func FuncAddr(fn any) uintptr
• func Register[T any](serializer SerializerFunc[T], deserializer DeserializerFunc[T])
• func RegisterClosure[Type, Closure any](name string)
• func RegisterFunc[Type any](name string)
• func Serialize(x any) []byte
• func SerializeT[T any](s *Serializer, x T)
• type Deserializer
• type DeserializerFunc
• type Field
• type Func
  • func FuncByAddr(addr uintptr) *Func
  • func FuncByName(name string) *Func
• type Serializer
• type SerializerFunc

Variables

var ErrBuildIDMismatch = errors.New("build ID mismatch")

ErrBuildIDMismatch is an error that occurs when a program attempts to deserialize objects from another build.

Functions

func Deserialize

func Deserialize(b []byte) (interface{}, []byte, error)

Deserialize value from b. Return left over bytes.

func DeserializeTo

func DeserializeTo[T any](d *Deserializer, x *T)

Deserialize a value to the provided non-nil pointer. See [RegisterSerde].

func FuncAddr

func FuncAddr(fn any) uintptr

FuncAddr returns the address in memory of the closure passed as argument.

This function can only resolve addresses of closures in the compilation unit that it is part of; for example, if compiled in a Go plugin, it can only resolve the address of functions within that plugin, and the main program cannot resolve addresses of functions in the plugins it loaded.

If the argument is a nil function value, the return address is zero.

The function panics if called with a value which is not a function.

func Register

func Register[T any](
	serializer SerializerFunc[T],
	deserializer DeserializerFunc[T])

Register attaches custom serialization and deserialization functions to type T.

Coroutine state is serialized and deserialized when calling [Context.Marshal] and [Context.Unmarshal] respectively.

Go basic types, structs, interfaces, slices, arrays, or any combination of them have built-in serialization and deserialization mechanisms. Channels and sync values do not.

Custom serializer and deserializer functions can be attached to types using Register to control how they are serialized, and possibly perform additional initialization on deserialization. Those functions are drivers for Serializer and Deserializer, that need to invoke Serialize and DeserializeTo in order to actually perform serialization and deserialization operations. Pointers to the same address are detected as such to be reconstructed as pointing to the same value. Slices are serialized by first serializing their backing array, and then length and capacity. As a result, slices sharing the same backing array are deserialized into one array with two shared slices, just like the original state was. Elements between length and capacity are also preserved.

func RegisterClosure

func RegisterClosure[Type, Closure any](name string)

RegisterClosure is like RegisterFunc but the caller can specify the closure type (see types.Func for details).

func RegisterFunc

func RegisterFunc[Type any](name string)

RegisterFunc is a helper function used to register function types. The type parameter must be a function type, but no compile nor runtime checks are used to enforce it; passing anything other than a function type will likely result in panics later on when the program attempts to serialize the function value.

The name argument is a unique identifier of the Go symbol that represents the function, which has the package path as prefix, and the dot-separated sequence identifying the function in the package.

func Serialize

func Serialize(x any) []byte

Serialize x.

The output of Serialize can be reconstructed back to a Go value using Deserialize.

func SerializeT

func SerializeT[T any](s *Serializer, x T)

Serialize a value. See [RegisterSerde].

Types

type Deserializer

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

type DeserializerFunc

type DeserializerFunc[T any] func(*Deserializer, *T) error

DeserializerFunc is the signature of customer deserializer functions. Use the Deserialize function to drive the Deserializer. Returning an error results in the program panicking.

type Field

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

type Func

type Func struct {
	// The address where the function exists in the program memory.
	Addr uintptr

	// The name that uniquely represents the function.
	//
	// For regular functions, this values has the form <package>.<function>.
	//
	// For closures, this value has the form <package>.<function>.func<N>, where
	// N starts at 1 and increments for each closure defined in the function.
	Name string

	// A type representing the signature of the function value.
	//
	// This field is nil if the type is unknown; by default the field is nil and
	// the program is expected to initialize it to a non-nil value for functions
	// that may be serialized.
	//
	// If non-nil, the type must be of kind reflect.Func.
	Type reflect.Type

	// A struct type representing the memory layout of the closure.
	//
	// This field is nil if the type is unknown; by default the field is nil and
	// the program is expected to initialize it to a non-nil value for closures
	// that may be serialized. For regular functions, this field can remain nil
	// since regular functions do not capture any values.
	//
	// If non-nil, the first field of the struct type must be a uintptr intended
	// to hold the address to the function value.
	Closure reflect.Type
}

Func represents a function in the program.

func FuncByAddr

func FuncByAddr(addr uintptr) *Func

FuncByAddr returns the function associated with the given address.

Addresses in the returned Func value hold the value of the symbol location in the program memory.

If the address passed as argument is not the address of a function in the program, the function returns nil.

func FuncByName

func FuncByName(name string) *Func

FuncByName returns the function associated with the given name.

Addresses in the returned Func value hold the value of the symbol location in the program memory.

If the name passed as argument does not represent any function, the function returns nil.

type Serializer

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

Serializer holds the state for serialization.

The ptrs value maps from pointers to IDs. Each time the serialization process encounters a pointer, it assigns it a new unique ID for its given address. This mechanism allows writing shared data only once. The actual value is written the first time a given pointer ID is encountered.

The containers value has ranges of memory held by container types. They are the values that actually own memory: structs and arrays.

Serialization starts with scanning the graph of values to find all the containers and add the range of memory they occupy into the map. Regions belong to the outermost container. For example:

struct X {
  struct Y {
    int
  }
}

creates only one container: the struct X. Both struct Y and the int are containers, but they are included in the region of struct X.

Those two mechanisms allow the deserialization of pointers that point to shared memory. Only outermost containers are serialized. All pointers either point to a container, or an offset into that container.

type SerializerFunc

type SerializerFunc[T any] func(*Serializer, *T) error

SerializerFunc is the signature of custom serializer functions. Use the Serialize function to drive the Serializer. Returning an error results in the program panicking.