scene

Documentation

Overview

The Tideland Go Library scene package 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
• func IsCleanupFailedError(err error) bool
• func IsPropAlreadyExistError(err error) bool
• func IsPropNotFoundError(err error) bool
• func IsSceneEndedError(err error) bool
• func IsTimeoutError(err error) bool
• func IsWaitedTooLongError(err error) bool
• func PackageVersion() version.Version
• type CleanupFunc
• type Scene
  • func Start() Scene
  • func StartLimited(inactivity, absolute time.Duration) Scene

Constants

const (
	ErrSceneEnded = iota + 1
	ErrTimeout
	ErrPropAlreadyExist
	ErrPropNotFound
	ErrCleanupFailed
	ErrWaitedTooLong
)

const (
	Active    = loop.Running
	Finishing = loop.Stopping
	Over      = loop.Stopped
)

Functions

func IsCleanupFailedError

func IsCleanupFailedError(err error) bool

IsCleanupFaildError returns true, if the error signals the failing of a prop error.

func IsPropAlreadyExistError

func IsPropAlreadyExistError(err error) bool

IsPropAlreadyExistError returns true, if the error signals a double prop key.

func IsPropNotFoundError

func IsPropNotFoundError(err error) bool

IsPropNotFoundError returns true, if the error signals a non-existing prop.

func IsSceneEndedError

func IsSceneEndedError(err error) bool

IsSceneEndedError returns true, if the error signals that the scene isn't active anymore.

func IsTimeoutError

func IsTimeoutError(err error) bool

IsTimeoutError returns true, if the error signals that the scene end after an absolute timeout.

func IsWaitedTooLongError

func IsWaitedTooLongError(err error) bool

IsWaitedTooLongError returns true, if the error signals a timeout when waiting for a signal.

func PackageVersion

func PackageVersion() version.Version

PackageVersion returns the version of the version package.

Types

type CleanupFunc

type CleanupFunc func(key string, prop interface{}) error

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 Start

func Start() Scene

Start creates and runs a new scene.

func StartLimited

func StartLimited(inactivity, absolute time.Duration) Scene

StartLimited creates and runs a new scene with an inactivity and an absolute timeout. They may be zero.