Skip to content

Commit 4a0c98e

Browse files
committed
add docs for runtime.go
1 parent e9f117e commit 4a0c98e

File tree

1 file changed

+26
-0
lines changed

1 file changed

+26
-0
lines changed

runtime.go

+26
Original file line numberDiff line numberDiff line change
@@ -8,35 +8,58 @@ import (
88
"time"
99
)
1010

11+
// Event represents a lifecycle event in the marshaling or unmarshalling
12+
// process.
1113
type Event int
1214

1315
const (
16+
// UnmarshalStart is the Event that is sent when deserialization of a payload
17+
// begins.
1418
UnmarshalStart Event = iota
19+
20+
// UnmarshalStop is the Event that is sent when deserialization of a payload
21+
// ends.
1522
UnmarshalStop
23+
24+
// MarshalStart is the Event that is sent sent when serialization of a payload
25+
// begins.
1626
MarshalStart
27+
28+
// MarshalStop is the Event that is sent sent when serialization of a payload
29+
// ends.
1730
MarshalStop
1831
)
1932

33+
// Runtime has the same methods as jsonapi package for serialization and
34+
// deserialization but also has a ctx, a map[string]interface{} for storing
35+
// state, designed for instrumenting serialization timings.
2036
type Runtime struct {
2137
ctx map[string]interface{}
2238
}
2339

40+
// Events is the func type that provides the callback for handling event timings.
2441
type Events func(*Runtime, Event, string, time.Duration)
2542

43+
// Instrumentation is a a global Events variable. This is the handler for all
44+
// timing events.
2645
var Instrumentation Events
2746

47+
// NewRuntime creates a Runtime for use in an application.
2848
func NewRuntime() *Runtime { return &Runtime{make(map[string]interface{})} }
2949

50+
// WithValue adds custom state variables to the runtime context.
3051
func (r *Runtime) WithValue(key string, value interface{}) *Runtime {
3152
r.ctx[key] = value
3253

3354
return r
3455
}
3556

57+
// Value returns a state variable in the runtime context.
3658
func (r *Runtime) Value(key string) interface{} {
3759
return r.ctx[key]
3860
}
3961

62+
// Instrument is deprecated.
4063
func (r *Runtime) Instrument(key string) *Runtime {
4164
return r.WithValue("instrument", key)
4265
}
@@ -45,12 +68,14 @@ func (r *Runtime) shouldInstrument() bool {
4568
return Instrumentation != nil
4669
}
4770

71+
// UnmarshalPayload has docs in request.go for UnmarshalPayload.
4872
func (r *Runtime) UnmarshalPayload(reader io.Reader, model interface{}) error {
4973
return r.instrumentCall(UnmarshalStart, UnmarshalStop, func() error {
5074
return UnmarshalPayload(reader, model)
5175
})
5276
}
5377

78+
// UnmarshalManyPayload has docs in request.go for UnmarshalManyPayload.
5479
func (r *Runtime) UnmarshalManyPayload(reader io.Reader, kind reflect.Type) (elems []interface{}, err error) {
5580
r.instrumentCall(UnmarshalStart, UnmarshalStop, func() error {
5681
elems, err = UnmarshalManyPayload(reader, kind)
@@ -60,6 +85,7 @@ func (r *Runtime) UnmarshalManyPayload(reader io.Reader, kind reflect.Type) (ele
6085
return
6186
}
6287

88+
// MarshalPayload has docs in response.go for MarshalPayload.
6389
func (r *Runtime) MarshalPayload(w io.Writer, model interface{}) error {
6490
return r.instrumentCall(MarshalStart, MarshalStop, func() error {
6591
return MarshalPayload(w, model)

0 commit comments

Comments
 (0)