Documentation
¶
Overview ¶
Package scene of the Tideland Go Library provides a shared access to common used data in a larger context.
By definition a scene is a sequence of continuous action in a play, movie, opera, or book. Applications do know these kind of scenes too, especially in concurrent software. Here aspects of the action have to passed between the actors in a secure way, very often they are interwoven and depending.
Here the scene package helps. Beside a simple atomic way to store and fetch information together with optional cleanup functions it handles inactivity and absolute timeouts.
A scene without timeouts is started with
scn := scene.Start()
Now props can be stored, fetched, and disposed.
err := scn.Store("foo", myFoo)
foo, err := scn.Fetch("foo")
foo, err := scn.Dispose("foo")
It's also possible to cleanup if a prop is disposed or the whole scene is stopped or aborted.
myCleanup := func(key string, prop interface{}) error {
// Cleanup, e.g. return the prop into a pool
// or close handles.
...
return nil
}
err := scn.StoreClean("foo", myFoo, myCleanup)
The cleanup is called individually per prop when disposing it, when the scene ends due to a timeout, or when it is stopped with
err := scn.Stop()
or
scn.Abort(myError)
Another functionality of the scene is the signaling of a topic. So multiple goroutines can wait for a signal with a topic, all will be notified after the topic has been signaled. Additionally they can wait with a timeout.
go func() {
err := scn.WaitFlag("foo")
...
}()
go func() {
err := scn.WaitFlagLimited("foo", 5 * time.Second)
...
}()
err := scn.Flag("foo")
In case a flag is already signaled wait immediatily returns. Store() and Flag() can also be combined to StoreAndFlag(). This way the key will be used as flag topic and a waiter knows that the information is available.
A scene knows two different timeouts. The first is the time of inactivity, the second is the absolute maximum time of a scene.
inactivityTimeout := 5 * time.Minutes absoluteTimeout := 60 * time.Minutes scn := scene.StartLimited(inactivityTimeout, absoluteTimeout)
Now the scene is stopped after 5 minutes without any access or at the latest 60 minutes after the start. Both value may be zero if not needed. So scene.StartLimited(0, 0) is the same as scene.Start().
Index ¶
Constants ¶
const ( ErrSceneEnded = iota + 1 ErrTimeout ErrPropAlreadyExist ErrPropNotFound ErrCleanupFailed ErrWaitedTooLong )
Error codes of the scene package.
Activity states of a scene.
Variables ¶
This section is empty.
Functions ¶
func IsCleanupFailedError ¶
IsCleanupFailedError returns true, if the error signals the failing of a prop error.
func IsPropAlreadyExistError ¶
IsPropAlreadyExistError returns true, if the error signals a double prop key.
func IsPropNotFoundError ¶
IsPropNotFoundError returns true, if the error signals a non-existing prop.
func IsSceneEndedError ¶
IsSceneEndedError returns true, if the error signals that the scene isn't active anymore.
func IsTimeoutError ¶
IsTimeoutError returns true, if the error signals that the scene end after an absolute timeout.
func IsWaitedTooLongError ¶
IsWaitedTooLongError returns true, if the error signals a timeout when waiting for a signal.
Types ¶
type CleanupFunc ¶
CleanupFunc is a function for the cleanup of props after a scene ended.
type Scene ¶
type Scene interface {
// ID returns the unique ID of the scene.
ID() identifier.UUID
// Stop tells the scene to end and waits until it is done.
Stop() error
// Abort tells the scene to end due to the passed error.
// Here only the first error will be stored for later evaluation.
Abort(err error)
// Wait blocks the caller until the scene ended and returns a
// possible error or nil.
Wait() error
// Status returns information about the current status of the scene.
Status() (int, error)
// Store stores a prop with a given key. The key must not exist.
Store(key string, prop interface{}) error
// StoreAndFlag stores a prop with a given key. The key must not exist.
// The storing is signaled with the key as topic.
StoreAndFlag(key string, prop interface{}) error
// StoreClean stores a prop with a given key and a cleanup
// function called when a scene ends. The key must not exist.
StoreClean(key string, prop interface{}, cleanup CleanupFunc) error
// StoreClean stores a prop with a given key and a cleanup
// function called when a scene ends. The key must not exist.
// The storing is signaled with the key as topic.
StoreCleanAndFlag(key string, prop interface{}, cleanup CleanupFunc) error
// Fetch retrieves a prop.
Fetch(key string) (interface{}, error)
// Dispose retrieves a prop and deletes it from the store.
Dispose(key string) (interface{}, error)
// Flag allows to signal a topic to interested actors.
Flag(topic string) error
// Unflag drops the signal for a given topic.
Unflag(topic string) error
// WaitFlag waits until the passed topic has been signaled.
WaitFlag(topic string) error
// WaitFlagAndFetch waits until the passed topic has been signaled.
// A prop stored at the topic as key is fetched.
WaitFlagAndFetch(topic string) (interface{}, error)
// WaitFlagLimited waits until the passed topic has been signaled
// or the timeout happened.
WaitFlagLimited(topic string, timeout time.Duration) error
// WaitFlagLimitedAndFetch waits until the passed topic has been signaled
// or the timeout happened. A prop stored at the topic as key is fetched.
WaitFlagLimitedAndFetch(topic string, timeout time.Duration) (interface{}, error)
}
Scene is the access point to one scene. It has to be created once for a continuous flow of operations and then passed between all functions and goroutine which are actors of the scene.
func StartLimited ¶
StartLimited creates and runs a new scene with an inactivity and an absolute timeout. They may be zero.
Source Files