Documentation
¶
Overview ¶
Package state provides functionality related to saving and loading object graphs. For most types, it provides a set of default saving / loading logic that will be invoked automatically if custom logic is not defined.
Kind Support ---- ------- Bool default Int default Int8 default Int16 default Int32 default Int64 default Uint default Uint8 default Uint16 default Uint32 default Uint64 default Float32 default Float64 default Complex64 default Complex128 default Array default Chan custom Func custom Interface default Map default Ptr default Slice default String default Struct custom (*) Unless zero-sized. UnsafePointer custom
See README.md for an overview of how encoding and decoding works.
Index ¶
- func CollectStats(enable bool)
- func EnableGraphEngine(enable bool)
- func Failf(fmtStr string, v ...any)
- func GraphEngineEnabled() bool
- func IsZeroValue(val any) bool
- func PrintGraph(w io.Writer, data []byte, graph uint64, asHTML bool) error
- func ReadHeader(r *wire.Reader) (length uint64, object bool, err error)
- func Register(t Type)
- func RegisterIdent(t, base StructType)
- func RegisterNoHooks(t StructType)
- func RegisterStruct(t StructType)
- func Release()
- func WriteHeader(w *wire.Writer, length uint64, object bool) error
- type AfterLoader
- type ErrState
- type Header
- type SaverLoader
- type Sink
- func (s Sink) Context() context.Context
- func (s Sink) Save(slot int, objPtr any)
- func (s Sink) SaveBool(slot int, v *bool)
- func (s Sink) SaveFloat32(slot int, v *float32)
- func (s Sink) SaveFloat64(slot int, v *float64)
- func (s Sink) SaveInt(slot int, v *int)
- func (s Sink) SaveInt8(slot int, v *int8)
- func (s Sink) SaveInt16(slot int, v *int16)
- func (s Sink) SaveInt32(slot int, v *int32)
- func (s Sink) SaveInt64(slot int, v *int64)
- func (s Sink) SaveString(slot int, v *string)
- func (s Sink) SaveUint(slot int, v *uint)
- func (s Sink) SaveUint8(slot int, v *uint8)
- func (s Sink) SaveUint16(slot int, v *uint16)
- func (s Sink) SaveUint32(slot int, v *uint32)
- func (s Sink) SaveUint64(slot int, v *uint64)
- func (s Sink) SaveUintptr(slot int, v *uintptr)
- func (s Sink) SaveValue(slot int, obj any)
- type Source
- func (s Source) AfterLoad(fn func())
- func (s Source) AfterLoadTo(l AfterLoader)
- func (s Source) Context() context.Context
- func (s Source) Load(slot int, objPtr any)
- func (s Source) LoadBool(slot int, v *bool)
- func (s Source) LoadFloat32(slot int, v *float32)
- func (s Source) LoadFloat64(slot int, v *float64)
- func (s Source) LoadInt(slot int, v *int)
- func (s Source) LoadInt8(slot int, v *int8)
- func (s Source) LoadInt16(slot int, v *int16)
- func (s Source) LoadInt32(slot int, v *int32)
- func (s Source) LoadInt64(slot int, v *int64)
- func (s Source) LoadString(slot int, v *string)
- func (s Source) LoadUint(slot int, v *uint)
- func (s Source) LoadUint8(slot int, v *uint8)
- func (s Source) LoadUint16(slot int, v *uint16)
- func (s Source) LoadUint32(slot int, v *uint32)
- func (s Source) LoadUint64(slot int, v *uint64)
- func (s Source) LoadUintptr(slot int, v *uintptr)
- func (s Source) LoadValue(slot int, objPtr any, fn func(any))
- func (s Source) LoadValueTo(slot int, typ any, l ValueLoader)
- func (s Source) LoadWait(slot int, objPtr any)
- type Stats
- type StructType
- type Type
- type ValueLoader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CollectStats ¶
func CollectStats(enable bool)
CollectStats enables or disables the collection of per-type timing statistics by the graph engine's Save and Load, which is costly.
func EnableGraphEngine ¶
func EnableGraphEngine(enable bool)
EnableGraphEngine enables or disables the reflection-free graph engine for Save. Load automatically detects which engine produced a stream from its header.
EnableGraphEngine mutates process-global state and must not be called concurrently with Save.
func Failf ¶
Failf is a wrapper around panic that should be used to generate errors that can be caught during saving and loading.
func GraphEngineEnabled ¶
func GraphEngineEnabled() bool
GraphEngineEnabled reports whether Save uses the reflection-free graph engine.
func IsZeroValue ¶
IsZeroValue checks if the given value is the zero value.
This function is used by the stateify tool.
func PrintGraph ¶
PrintGraph prints a single graph-engine object graph from data, as text or HTML.
Since streams don't describe the types of fields, they can only be printed by the binary that saved them. Objects are decoded without running their load callbacks.
func ReadHeader ¶
ReadHeader reads an object header.
Each object written to the statefile is prefixed with a header. See WriteHeader for more information; these functions are exported to allow non-state writes to the file to play nice with debugging tools.
func Register ¶
func Register(t Type)
Register registers a type.
This must be called on init and only done once. Registration lets Load reconstruct concrete types held in interfaces without a preceding Save.
func RegisterIdent ¶
func RegisterIdent(t, base StructType)
RegisterIdent registers a struct type defined over base (+stateify identtype), inheriting base's RegisterNoHooks property regardless of init order.
This must be called on init and only done once.
func RegisterNoHooks ¶
func RegisterNoHooks(t StructType)
RegisterNoHooks registers a struct type whose StateSave and StateLoad methods save and load its fields, and do nothing else, like RegisterStruct. The state package may save values of the type without calling these methods.
This must be called on init and only done once.
func RegisterStruct ¶
func RegisterStruct(t StructType)
RegisterStruct registers a struct type, like Register. Passing the type as a StructType makes the interface table of StructType for the type static, so that the state package does not build it at run time.
This must be called on init and only done once.
func Release ¶
func Release()
Release releases references to global type databases. Must only be called in contexts where they will definitely never be used, in order to save memory.
func WriteHeader ¶
WriteHeader writes a header.
Each object written to the statefile should be prefixed with a header. In order to generate statefiles that play nicely with debugging tools, raw writes should be prefixed with a header with object set to false and the appropriate length. This will allow tools to skip these regions.
Types ¶
type AfterLoader ¶
type AfterLoader interface {
// StateAfterLoad calls the afterLoad method.
StateAfterLoad(ctx context.Context)
}
AfterLoader is implemented by the generated code of structs with afterLoad methods (see Source.AfterLoadTo).
type ErrState ¶
type ErrState struct {
// contains filtered or unexported fields
}
ErrState is returned when an error is encountered during encode/decode.
type Header ¶
type Header struct {
// Length is the payload length: for legacy object graphs, the number of
// wire objects; for graph-engine object graphs and non-object regions,
// the length in bytes.
Length uint64
// Object reports whether this region is an encoded object graph rather
// than raw non-state data.
Object bool
// Graph reports whether an object graph uses the graph engine format.
Graph bool
}
Header describes a framed region in a statefile stream.
type SaverLoader ¶
type SaverLoader interface {
// StateSave saves the state of the object to the given Map.
StateSave(Sink)
// StateLoad loads the state of the object.
StateLoad(context.Context, Source)
}
SaverLoader defines a struct's state methods.
type Sink ¶
type Sink struct {
// contains filtered or unexported fields
}
Sink is used for Type.StateSave.
func (Sink) Save ¶
Save adds the given object to the map.
You should pass always pointers to the object you are saving. For example:
type X struct {
A int
B *int
}
func (x *X) StateTypeInfo(m Sink) state.TypeInfo {
return state.TypeInfo{
Name: "pkg.X",
Fields: []string{
"A",
"B",
},
}
}
func (x *X) StateSave(m Sink) {
m.Save(0, &x.A) // Field is A.
m.Save(1, &x.B) // Field is B.
}
func (x *X) StateLoad(m Source) {
m.Load(0, &x.A) // Field is A.
m.Load(1, &x.B) // Field is B.
}
func (Sink) SaveFloat32 ¶
SaveFloat32 saves a float32 field. See Save.
func (Sink) SaveFloat64 ¶
SaveFloat64 saves a float64 field. See Save.
func (Sink) SaveString ¶
SaveString saves a string field. See Save.
func (Sink) SaveUint16 ¶
SaveUint16 saves a uint16 field. See Save.
func (Sink) SaveUint32 ¶
SaveUint32 saves a uint32 field. See Save.
func (Sink) SaveUint64 ¶
SaveUint64 saves a uint64 field. See Save.
func (Sink) SaveUintptr ¶
SaveUintptr saves a uintptr field. See Save.
func (Sink) SaveValue ¶
SaveValue adds the given object value to the map.
This should be used for values where pointers are not available, or casts are required during Save/Load.
For example, if we want to cast external package type P.Foo to int64:
func (x *X) StateSave(m Sink) {
m.SaveValue(0, "A", int64(x.A))
}
func (x *X) StateLoad(m Source) {
m.LoadValue(0, new(int64), func(x any) {
x.A = P.Foo(x.(int64))
})
}
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
Source is used for Type.StateLoad.
func (Source) AfterLoad ¶
func (s Source) AfterLoad(fn func())
AfterLoad schedules a function execution when all objects have been allocated and their automated loading and customized load logic have been executed. fn will not be executed until all of current object's dependencies' AfterLoad() logic, if exist, have been executed.
func (Source) AfterLoadTo ¶
func (s Source) AfterLoadTo(l AfterLoader)
AfterLoadTo is like AfterLoad, but calls l.StateAfterLoad.
This is used by go_stateify, and avoids the allocation of a function.
func (Source) Load ¶
Load loads the given object passed as a pointer..
See Sink.Save for an example.
func (Source) LoadFloat32 ¶
LoadFloat32 loads a float32 field. See Load.
func (Source) LoadFloat64 ¶
LoadFloat64 loads a float64 field. See Load.
func (Source) LoadString ¶
LoadString loads a string field. See Load.
func (Source) LoadUint16 ¶
LoadUint16 loads a uint16 field. See Load.
func (Source) LoadUint32 ¶
LoadUint32 loads a uint32 field. See Load.
func (Source) LoadUint64 ¶
LoadUint64 loads a uint64 field. See Load.
func (Source) LoadUintptr ¶
LoadUintptr loads a uintptr field. See Load.
func (Source) LoadValue ¶
LoadValue loads the given object value from the map.
See Sink.SaveValue for an example.
func (Source) LoadValueTo ¶
func (s Source) LoadValueTo(slot int, typ any, l ValueLoader)
LoadValueTo is like LoadValue, but calls l.StateLoadValue(ctx, slot, value) instead of a function. typ is a nil pointer to the type of the value. StateLoadValue must not retain the address of the value, which it must copy.
This is used by go_stateify, and avoids the allocations of LoadValue.
type Stats ¶
type Stats struct {
// contains filtered or unexported fields
}
Stats tracks encode / decode timing.
This currently provides a meaningful String function and no other way to extract stats about individual types.
All exported receivers accept nil.
type StructType ¶
type StructType interface {
Type
SaverLoader
}
StructType is implemented by pointers to struct types with state methods.
type Type ¶
type Type interface {
// StateTypeName returns the type's name.
//
// This is used for matching type information during encoding and
// decoding, as well as dynamic interface dispatch. This should be
// globally unique.
StateTypeName() string
// StateFields returns information about the type.
//
// Fields is the set of fields for the object. Calls to Sink.Save and
// Source.Load must be made in-order with respect to these fields.
//
// The field list must be stable for the type.
StateFields() []string
}
Type describes a type's saved representation while minimizing runtime reflection. The package separately registers binary codecs for supported foreign structs.
All these methods can be automatically generated by the go_stateify tool.
Source Files
¶
- decode.go
- decode_unsafe.go
- encode.go
- encode_unsafe.go
- graph_addrmap.go
- graph_buf_unsafe.go
- graph_decode_callbacks_unsafe.go
- graph_decode_unsafe.go
- graph_decode_values_unsafe.go
- graph_encode_objects_unsafe.go
- graph_encode_stream_unsafe.go
- graph_encode_unsafe.go
- graph_encode_values_unsafe.go
- graph_print_unsafe.go
- graph_typecache_unsafe.go
- graph_typeinfo_unsafe.go
- state.go
- state_norace.go
- stats.go
- typed.go
- types.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package pretty is a pretty-printer for state streams.
|
Package pretty is a pretty-printer for state streams. |
|
Package statefile defines the state file data stream.
|
Package statefile defines the state file data stream. |
|
Package tests tests the state packages.
|
Package tests tests the state packages. |
|
Package wire contains a few basic types that can be composed to serialize graph information for the state package.
|
Package wire contains a few basic types that can be composed to serialize graph information for the state package. |