1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
// Tideland Go Library - Scene
//
// Copyright (C) 2014-2017 Frank Mueller / Tideland / Oldenburg / Germany
//
// All rights reserved. Use of this source code is governed
// by the new BSD license.
// 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().
package scene
// EOF
|
