Documentation ¶
Overview ¶
Package cancel - convenient cancellation for cli based cmd's.
Function names match the underlying context package - just: their call signatures do not need any parent context.
And: they build upon each other: You'll need only one.
Choose exactly one from:
- WithCancel() - includes BackGround, and listen
- WithTimeout(...) - includes WithCancel, and waiter
- WithDeadline(...) - includes WithCancel, and waiter
to get Your observed base context.
When You like to switch-off any cancellation (temporarily), You may use
- BackGround()
as a convenience (without any need to adjust Your import statements).
Note: "Don't `panic`"! Extra checks protect You against accidental misuse and `panic` upon any subsequent use, unless You explicitly call `ReStart()` before.
Technical note: WithCancel, WithTimeout and WithDeadline return to You
- a context (child =Timeout/Deadline) - You may derive further from it
- a CancelFunc (parent = Cancel) in case You dare to use it.
Just: Most often You may safely ignore the CancelFunc, as `listen` and `waiter` take care of it. Thus, You need not to worry about any leaking.
Be a happy gopher :-)
Index ¶
- func BackGround() (ctx context.Context)
- func Done(ctx context.Context) func() bool
- func ReStart()
- func WithCancel() (ctx context.Context, cancel context.CancelFunc)
- func WithDeadline(deadline time.Time) (ctx context.Context, cancel context.CancelFunc)
- func WithTimeout(timeout time.Duration) (ctx context.Context, cancel context.CancelFunc)
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BackGround ¶
BackGround just gives You an initial root context (context.Background()) without any functionality.
Note: only exported as convenience - similar to the context package. Use one of the more advanced `WithXyz`-functions instead.
Example ¶
package main import ( "context" "time" "github.com/GoLangsam/do/cli/cancel" ) func mainOperation(ctx context.Context) { time.Sleep(33 * time.Millisecond) println("Working completed") return } func main() { cancel.ReStart() // no need in Your main.go root := cancel.BackGround() ctx, cancel := context.WithCancel(root) // use it to derive Your own child context mainOperation(ctx) <-ctx.Done() cancel() }
Output:
func Done ¶
Done returns a do.Nok which returns false unless the given context has been cancelled.
Done is a convenience.
func ReStart ¶
func ReStart()
ReStart permits You to call any of the `WithXyz`-functions again.
Example ¶
package main import ( "github.com/GoLangsam/do/cli/cancel" ) func main() { cancel.ReStart() // no need in Your main.go }
Output:
func WithCancel ¶
func WithCancel() (ctx context.Context, cancel context.CancelFunc)
WithCancel gives You an initial root context (and it's CancelFunc) and spawns `listen` which cancels the context upon any cancellation event.
Example ¶
package main import ( "context" "time" "github.com/GoLangsam/do/cli/cancel" ) func mainOperation(ctx context.Context) { time.Sleep(33 * time.Millisecond) println("Working completed") return } func main() { cancel.ReStart() // no need in Your main.go ctx, cancel := cancel.WithCancel() mainOperation(ctx) // pretend to be busy cancel() <-ctx.Done() }
Output:
func WithDeadline ¶
WithDeadline gives You an initial root context (and a CancelFunc) and spawns `waiter` which cancels the context upon
- any cancellation event
- deadline expires
whichever is seen first
Example ¶
package main import ( "context" "time" "github.com/GoLangsam/do/cli/cancel" ) func doneMainOperation(ctx context.Context) <-chan struct{} { cha := make(chan struct{}) go func() { defer close(cha) time.Sleep(33 * time.Millisecond) println("Working completed") cha <- struct{}{} }() return cha } func main() { cancel.ReStart() // no need in Your main.go ctx, _ := cancel.WithDeadline(time.Now().Add(100 * time.Millisecond)) done := doneMainOperation(ctx) // pretend to be busy 'till dawn select { case <-done: println("Mission completed") case <-ctx.Done(): println("Mission aborted") } }
Output:
func WithTimeout ¶
WithTimeout gives You an initial rooted context (and a CancelFunc) and spawns `waiter` which cancels the context upon
- any cancellation event
- timeout elapses
whichever is seen first Note: WithTimeout is simply a convenience for `WithDeadline(time.Now().Add(timeout))`.
Example ¶
package main import ( "context" "time" "github.com/GoLangsam/do/cli/cancel" ) func mainOperation(ctx context.Context) { time.Sleep(33 * time.Millisecond) println("Working completed") return } func main() { cancel.ReStart() // no need in Your main.go ctx, cancel := cancel.WithTimeout(100 * time.Millisecond) mainOperation(ctx) // pretend to be busy cancel() // mainOperation finished: no more need to await timeout <-ctx.Done() }
Output:
Types ¶
This section is empty.