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 ¶ added in v0.1.1
Deserialize value from b. Return left over bytes.
func DeserializeTo ¶ added in v0.1.1
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 ¶ added in v0.1.1
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 ¶ added in v0.1.1
Serialize x.
The output of Serialize can be reconstructed back to a Go value using Deserialize.
func SerializeT ¶ added in v0.1.1
func SerializeT[T any](s *Serializer, x T)
Serialize a value. See [RegisterSerde].
Types ¶
type Deserializer ¶ added in v0.1.1
type Deserializer struct {
// contains filtered or unexported fields
}
type DeserializerFunc ¶ added in v0.1.1
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 ¶ added in v0.1.1
type Field struct {
// contains filtered or unexported fields
}
Field is a struct field.
func (*Field) Anonymous ¶ added in v0.4.0
Anonymous is true of the field is an embedded field (with a name derived from its type).
func (*Field) Offset ¶ added in v0.4.0
Offset is the offset of the field within its struct, in bytes.
func (*Field) Package ¶ added in v0.4.0
Package is the package path that qualifies a lwer case (unexported) field name. It is empty for upper case (exported) field names.
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 ¶ added in v0.4.0
type Function struct {
// contains filtered or unexported fields
}
Function is a function, method or closure referenced by the coroutine.
func (*Function) ClosureType ¶ added in v0.4.0
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.
func (*Function) Index ¶ added in v0.4.2
Index is the index of the function in the serialized state.
type Region ¶ added in v0.4.0
type Region struct {
// contains filtered or unexported fields
}
Region is a region of memory referenced by the coroutine.
func (*Region) Index ¶ added in v0.4.2
Index is the index of the region in the serialized state, or -1 if this is the root region.
type Scanner ¶ added in v0.4.2
type Scanner struct {
// contains filtered or unexported fields
}
Scanner scans a Region.
func (*Scanner) Close ¶ added in v0.4.2
Close closes the scanner and returns any errors that occurred during scanning.
func (*Scanner) Complex128 ¶ added in v0.4.2
func (s *Scanner) Complex128() complex128
Complex128 returns the complex128 the scanner points to.
func (*Scanner) Custom ¶ added in v0.4.2
Custom is true if the scanner is scanning an object for which a custom serializer was registered.
func (*Scanner) Len ¶ added in v0.4.2
Len is the length of the string, slice, array or map the scanner is pointing to.
func (*Scanner) Pos ¶ added in v0.4.2
Pos is the position of the scanner, in terms of number of bytes into the region.
func (*Scanner) Region ¶ added in v0.4.2
Region is the region and offset the scanner is pointing to.
type Serializer ¶ added in v0.1.1
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 ¶ added in v0.1.1
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 ¶ added in v0.4.0
type State struct {
// contains filtered or unexported fields
}
State wraps durable coroutine state.
func Inspect ¶ added in v0.4.0
Inspect inspects serialized durable coroutine state.
The input should be a buffer produced by (*coroutine.Context).Marshal or by types.Serialize.
func (*State) BuildID ¶ added in v0.4.0
BuildID returns the build ID of the program that generated this state.
func (*State) NumFunction ¶ added in v0.4.0
NumFunction returns the number of functions/methods/closures referenced by the coroutine.
func (*State) NumRegion ¶ added in v0.4.0
NumRegion returns the number of memory regions referenced by the coroutine.
func (*State) NumString ¶ added in v0.4.0
NumString returns the number of strings referenced by types.
func (*State) NumType ¶ added in v0.4.0
NumType returns the number of types referenced by the coroutine.
type Type ¶ added in v0.4.0
type Type struct {
// contains filtered or unexported fields
}
Type is a type referenced by a durable coroutine.
func (*Type) Elem ¶ added in v0.4.0
Elem is the type of an array, slice, pointer, chan or map's element.
func (*Type) Index ¶ added in v0.4.2
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 ¶ added in v0.4.0
MemoryOffset is the location of this type in memory.
The offset is only applicable to the build that generated the state.
func (*Type) Opaque ¶ added in v0.4.1
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.
func (*Type) Param ¶ added in v0.4.0
Param is the type of a function parameter with the specified index.
Source Files