Documentation ¶
Overview ¶
Copyright 2023 CloudWeGo Authors
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Index ¶
- Constants
- func BindSession(s Session)
- func Go(f func())
- func GoSession(s Session, f func())
- func InitDefaultManager(opts ManagerOptions)
- func UnbindSession()
- type ManagerOptions
- type Session
- type SessionCtx
- type SessionID
- type SessionManager
- func (self *SessionManager) BindSession(id SessionID, s Session)
- func (self SessionManager) Close()
- func (self SessionManager) GC()
- func (self *SessionManager) GetSession(id SessionID) (Session, bool)
- func (self SessionManager) Options() ManagerOptions
- func (self *SessionManager) UnbindSession(id SessionID)
- type SessionMap
Examples ¶
Constants ¶
const Pprof_Label_Session_ID = "go_session_id"
const SESSION_CONFIG_KEY = "CLOUDWEGO_SESSION_CONFIG_KEY"
SESSION_CONFIG_KEY is the env key for configuring default session manager.
Value format: [EnableImplicitlyTransmitAsync][,ShardNumber][,GCInterval] - EnableImplicitlyTransmitAsync: 'true' means enabled, otherwist means disabled - ShardNumber: integer > 0 - GCInterval: Golang time.Duration format, such as '10m' means ten minutes for each GC
Once the key is set, default option values will be set if the option value doesn't exist.
Variables ¶
This section is empty.
Functions ¶
func BindSession ¶
func BindSession(s Session)
BindSession binds the session with current goroutine
NOTICE: MUST call `InitDefaultManager()` once before using this API
func Go ¶
func Go(f func())
Go calls f asynchronously and pass caller's session to the new goroutine
func GoSession ¶
func GoSession(s Session, f func())
SessionGo calls f asynchronously and pass s session to the new goroutine
func InitDefaultManager ¶ added in v0.0.2
func InitDefaultManager(opts ManagerOptions)
InitDefaultManager update and restart default manager. It accept argument opts and env config both.
NOTICE:
- It use env SESSION_CONFIG_KEY prior to argument opts;
- If both env and opts are empty, it won't reset manager;
- For concurrent safety, you can only successfully reset manager ONCE.
func UnbindSession ¶
func UnbindSession()
UnbindSession unbind a session (if any) with current goroutine
NOTICE: If you want to end the session, please call `Disable()` (or whatever make the session invalid) on your session's implementation
NOTICE: MUST call `InitDefaultManager()` once before using this API
Types ¶
type ManagerOptions ¶
type ManagerOptions struct { // EnableImplicitlyTransmitAsync enables transparently transmit // current session to children goroutines // // WARNING: Once this option enables, if you want to use `pprof.Do()`, it must be called before `BindSession()`, // otherwise transmitting will be dysfunctional EnableImplicitlyTransmitAsync bool // ShardNumber is used to shard session id, it must be larger than zero ShardNumber int // GCInterval decides the GC interval for SessionManager, // it must be larger than 1s or zero means disable GC GCInterval time.Duration }
ManagerOptions for SessionManager
func DefaultManagerOptions ¶ added in v0.0.2
func DefaultManagerOptions() ManagerOptions
DefaultManagerOptions returns default options for the default manager
type Session ¶
type Session interface { // IsValid tells if the session is valid at present IsValid() bool // Get returns value for specific key Get(key interface{}) interface{} // WithValue sets value for specific key,and return newly effective session WithValue(key interface{}, val interface{}) Session }
Session represents a local storage for one session
func CurSession ¶
CurSession gets the session for current goroutine
NOTICE: MUST call `InitDefaultManager()` once before using this API
type SessionCtx ¶
type SessionCtx struct {
// contains filtered or unexported fields
}
SessionCtx implements Session with context, which means children session WON'T affect parent and sibling sessions
Example ¶
// initialize default manager first InitDefaultManager(DefaultManagerOptions()) var ctx = context.Background() var key, v = "a", "b" var key2, v2 = "c", "d" var sig = make(chan struct{}) var sig2 = make(chan struct{}) // initialize new session with context var session = NewSessionCtx(ctx) // implementation... // set specific key-value and update session start := session.WithValue(key, v) // set current session BindSession(start) // pass to new goroutine... Go(func() { // read specific key under current session val := GetCurSession().Get(key) // val exists ASSERT(val == v) // doSomething.... // set specific key-value under current session // NOTICE: current session won't change here next := GetCurSession().WithValue(key2, v2) val2 := GetCurSession().Get(key2) // val2 == nil ASSERT(val2 == nil) // pass both parent session and new session to sub goroutine GoSession(next, func() { // read specific key under current session val := GetCurSession().Get(key) // val exists ASSERT(val == v) val2 := GetCurSession().Get(key2) // val2 exists ASSERT(val2 == v2) // doSomething.... sig2 <- struct{}{} <-sig ASSERT(GetCurSession().IsValid() == false) // current session is invalid println("g2 done") sig2 <- struct{}{} }) Go(func() { // read specific key under current session val := GetCurSession().Get(key) // val exists ASSERT(v == val) val2 := GetCurSession().Get(key2) // val2 == nil ASSERT(val2 == nil) // doSomething.... sig2 <- struct{}{} <-sig ASSERT(GetCurSession().IsValid() == false) // current session is invalid println("g3 done") sig2 <- struct{}{} }) BindSession(next) val2 = GetCurSession().Get(key2) // val2 exists ASSERT(v2 == val2) sig2 <- struct{}{} <-sig ASSERT(next.IsValid() == false) // next is invalid println("g1 done") sig2 <- struct{}{} }) <-sig2 <-sig2 <-sig2 val2 := GetCurSession().Get(key2) // val2 == nil ASSERT(val2 == nil) // initiatively ends the session, // then all the inherited session (including next) will be disabled session.Disable() close(sig) ASSERT(start.IsValid() == false) // start is invalid <-sig2 <-sig2 <-sig2 println("g0 done") UnbindSession()
Output:
func NewSessionCtx ¶
func NewSessionCtx(ctx context.Context) SessionCtx
NewSessionCtx creates and enables a SessionCtx
func NewSessionCtxWithTimeout ¶
func NewSessionCtxWithTimeout(ctx context.Context, timeout time.Duration) SessionCtx
NewSessionCtx creates and enables a SessionCtx, and disable the session after timeout
func (SessionCtx) Export ¶ added in v0.0.2
func (self SessionCtx) Export() context.Context
Export exports underlying context
func (SessionCtx) Get ¶
func (self SessionCtx) Get(key interface{}) interface{}
Get value for specific key
func (SessionCtx) IsValid ¶
func (self SessionCtx) IsValid() bool
IsValid tells if the session is valid at present
func (SessionCtx) WithValue ¶
func (self SessionCtx) WithValue(key interface{}, val interface{}) Session
Set value for specific key,and return newly effective session
type SessionManager ¶
type SessionManager struct {
// contains filtered or unexported fields
}
SessionManager maintain and manage sessions
func NewSessionManager ¶
func NewSessionManager(opts ManagerOptions) SessionManager
NewSessionManager creates a SessionManager with default containers If opts.GCInterval > 0, it will start scheduled GC() loop automatically
func (*SessionManager) BindSession ¶
func (self *SessionManager) BindSession(id SessionID, s Session)
BindSession binds the session with current goroutine
func (SessionManager) Close ¶
func (self SessionManager) Close()
Close stop persistent work for the manager, like GC
func (SessionManager) GC ¶
func (self SessionManager) GC()
GC sweep invalid sessions and release unused memory
func (*SessionManager) GetSession ¶
func (self *SessionManager) GetSession(id SessionID) (Session, bool)
Get gets specific session or get inherited session if option EnableImplicitlyTransmitAsync is true
func (SessionManager) Options ¶
func (self SessionManager) Options() ManagerOptions
Options shows the manager's Options
func (*SessionManager) UnbindSession ¶
func (self *SessionManager) UnbindSession(id SessionID)
UnbindSession clears current session
Notice: If you want to end the session, please call `Disable()` (or whatever make the session invalid) on your session's implementation
type SessionMap ¶
type SessionMap struct {
// contains filtered or unexported fields
}
NewSessionMap implements Session with map, which means children session WILL affect parent session and sibling sessions
func NewSessionMap ¶
func NewSessionMap(m map[interface{}]interface{}) *SessionMap
NewSessionMap creates and enables a SessionMap
func NewSessionMapWithTimeout ¶
func NewSessionMapWithTimeout(m map[interface{}]interface{}, timeout time.Duration) *SessionMap
NewSessionCtx creates and enables a SessionCtx, and disable the session after timeout
func (*SessionMap) Export ¶ added in v0.0.2
func (self *SessionMap) Export() map[interface{}]interface{}
Export COPIES and exports underlying map
func (*SessionMap) Get ¶
func (self *SessionMap) Get(key interface{}) interface{}
Get value for specific key
func (*SessionMap) IsValid ¶
func (self *SessionMap) IsValid() bool
IsValid tells if the session is valid at present
func (*SessionMap) WithValue ¶
func (self *SessionMap) WithValue(key interface{}, val interface{}) Session
Set value for specific key,and return itself