Documentation
¶
Overview ¶
Package types contains the infrastructure needed to support serialization of Go types.
Index ¶
- Variables
- func Deserialize(b []byte) (x interface{}, err 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, error)
- func SerializeT[T any](s *Serializer, x T)
- type Deserializer
- type DeserializerFunc
- type Field
- type Func
- type Function
- type Region
- type Scanner
- func (s *Scanner) Bool() bool
- func (s *Scanner) Cap() int
- func (s *Scanner) Close() error
- func (s *Scanner) Complex128() complex128
- func (s *Scanner) Complex64() complex64
- func (s *Scanner) Custom() bool
- func (s *Scanner) Depth() int
- func (s *Scanner) Field() *Field
- func (s *Scanner) Float32() float32
- func (s *Scanner) Float64() float64
- func (s *Scanner) Function() *Function
- func (s *Scanner) Int() int
- func (s *Scanner) Int16() int16
- func (s *Scanner) Int32() int32
- func (s *Scanner) Int64() int64
- func (s *Scanner) Int8() int8
- func (s *Scanner) Kind() reflect.Kind
- func (s *Scanner) Len() int
- func (s *Scanner) Next() bool
- func (s *Scanner) Nil() bool
- func (s *Scanner) Pos() int
- func (s *Scanner) Region() (*Region, int64)
- func (s *Scanner) Type() *Type
- func (s *Scanner) Uint() uint
- func (s *Scanner) Uint16() uint16
- func (s *Scanner) Uint32() uint32
- func (s *Scanner) Uint64() uint64
- func (s *Scanner) Uint8() uint8
- func (s *Scanner) Uintptr() uintptr
- type Serializer
- type SerializerFunc
- type State
- func (s *State) Arch() string
- func (s *State) BuildID() string
- func (s *State) Function(i int) *Function
- func (s *State) NumFunction() int
- func (s *State) NumRegion() int
- func (s *State) NumString() int
- func (s *State) NumType() int
- func (s *State) OS() string
- func (s *State) Region(i int) *Region
- func (s *State) Root() *Region
- func (s *State) String(i int) string
- func (s *State) Type(i int) *Type
- type Type
- func (t *Type) ChanDir() reflect.ChanDir
- func (t *Type) Elem() *Type
- func (t *Type) Field(i int) *Field
- func (t *Type) Format(s fmt.State, v rune)
- func (t *Type) Index() int
- func (t *Type) Key() *Type
- func (t *Type) Kind() reflect.Kind
- func (t *Type) Len() int
- func (t *Type) MemoryOffset() uint64
- func (t *Type) Name() string
- func (t *Type) NumField() int
- func (t *Type) NumParam() int
- func (t *Type) NumResult() int
- func (t *Type) Opaque() bool
- func (t *Type) Package() string
- func (t *Type) Param(i int) *Type
- func (t *Type) Result(i int) *Type
- func (t *Type) Variadic() bool
Constants ¶
This section is empty.
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 ¶
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 ¶
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 ¶
RegisterClosure is like RegisterFunc but the caller can specify the closure type (see types.Func for details).
func RegisterFunc ¶
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 ¶
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
}
Field is a struct field.
func (*Field) Anonymous ¶
Anonymous is true of the field is an embedded field (with a name derived from its type).
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 ¶
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 ¶
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 Function ¶
type Function struct {
// contains filtered or unexported fields
}
Function is a function, method or closure referenced by the coroutine.
func (*Function) ClosureType ¶
ClosureType returns the memory layout for closure functions.
The returned type is a struct where the first field is a function pointer and the remaining fields are the variables from outer scopes that are referenced by the closure.
Nil is returned for functions that are not closures.
type Region ¶
type Region struct {
// contains filtered or unexported fields
}
Region is a region of memory referenced by the coroutine.
func (*Region) Index ¶
Index is the index of the region in the serialized state, or -1 if this is the root region.
type Scanner ¶
type Scanner struct {
// contains filtered or unexported fields
}
Scanner scans a Region.
func (*Scanner) Close ¶
Close closes the scanner and returns any errors that occurred during scanning.
func (*Scanner) Complex128 ¶
func (s *Scanner) Complex128() complex128
Complex128 returns the complex128 the scanner points to.
func (*Scanner) Custom ¶
Custom is true if the scanner is scanning an object for which a custom serializer was registered.
func (*Scanner) Len ¶
Len is the length of the string, slice, array or map the scanner is pointing to.
func (*Scanner) Pos ¶
Pos is the position of the scanner, in terms of number of bytes into the region.
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.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State wraps durable coroutine state.
func Inspect ¶
Inspect inspects serialized durable coroutine state.
The input should be a buffer produced by (*coroutine.Context).Marshal or by types.Serialize.
func (*State) NumFunction ¶
NumFunction returns the number of functions/methods/closures referenced by the coroutine.
func (*State) NumRegion ¶
NumRegion returns the number of memory regions referenced by the coroutine.
type Type ¶
type Type struct {
// contains filtered or unexported fields
}
Type is a type referenced by a durable coroutine.
func (*Type) Index ¶
Index is the index of the type in the serialized state, or -1 if the type is derived from a serialized type.
func (*Type) MemoryOffset ¶
MemoryOffset is the location of this type in memory.
The offset is only applicable to the build that generated the state.
func (*Type) Opaque ¶
Opaue is true for types that had a custom serializer registered in the program that generated the coroutine state. Custom types are opaque and cannot be inspected.
Source Files