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()
}
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
}
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()
}
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")
}
}
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()
}
Types ¶
This section is empty.
Source Files
Directories