Documentation ¶
Overview ¶
Package schedgroup provides a goroutine worker pool which schedules tasks to be performed at or after a specified time.
Special thanks to Egon Elbre from #performance on Gophers Slack for two prototypes (https://play.golang.org/p/YyeSWuDil-b, https://play.golang.org/p/4iYBO6Cgj8m) of this idea, based on Go's container/heap package. Egon's prototypes heavily influenced the final design of this package.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Group ¶
type Group struct {
// contains filtered or unexported fields
}
A Group is a goroutine worker pool which schedules tasks to be performed after a specified time. A Group must be created with the New constructor. Once Wait is called, New must be called to create a new Group to schedule more tasks.
Example (Cancelation) ¶
This example demonstrates how context cancelation/timeout effects a Group.
package main import ( "context" "fmt" "log" "time" "github.com/mdlayher/schedgroup" ) func main() { // Create a Group which will use a context's timeout for cancelation. ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond) defer cancel() sg := schedgroup.New(ctx) // Schedule multiple tasks to occur at different times relative to a point // in time. start := time.Now() // Schedule a task which will not be run before a timeout occurs. sg.Schedule(start.Add(1*time.Second), func() { // This panic would normally crash the program, but this task will // never be run. panic("this shouldn't happen!") }) // Schedule tasks which will occur before timeout. Tasks which are scheduled // for an earlier time will occur first. sg.Schedule(start.Add(200*time.Millisecond), func() { fmt.Println("world") }) sg.Schedule(start.Add(100*time.Millisecond), func() { fmt.Println("hello") }) // Wait for task completion or timeout. switch err := sg.Wait(); err { case nil: panic("all tasks should not have completed!") case context.DeadlineExceeded: // No problem, we expected this to occur. fmt.Println("timeout!") default: log.Fatalf("failed to wait: %v", err) } }
Output: hello world timeout!
Example (Wait) ¶
This example demonstrates typical use of a Group.
package main import ( "context" "fmt" "log" "time" "github.com/mdlayher/schedgroup" ) func main() { // Create a Group which will not use a context for cancelation. sg := schedgroup.New(context.Background()) // Schedule tasks to run in 100, 200, and 300 milliseconds which will print // the number n to the screen. for i := 0; i < 3; i++ { n := i + 1 sg.Delay(time.Duration(n)*100*time.Millisecond, func() { fmt.Println(n) }) } // Wait for all of the scheduled tasks to complete. if err := sg.Wait(); err != nil { log.Fatalf("failed to wait: %v", err) } }
Output: 1 2 3
func New ¶
New creates a new Group which will use ctx for cancelation. If cancelation is not a concern, use context.Background().
func (*Group) Delay ¶
Delay schedules a function to run at or after the specified delay. Delay is a convenience wrapper for Schedule which adds delay to the current time. Specifying a negative delay will cause the task to be scheduled immediately.
If Delay is called after a call to Wait, Delay will panic.
func (*Group) Schedule ¶
Schedule schedules a function to run at or after the specified time. Specifying a past time will cause the task to be scheduled immediately.
If Schedule is called after a call to Wait, Schedule will panic.
func (*Group) Wait ¶
Wait waits for the completion of all scheduled tasks, or for cancelation of the context passed to New. Wait will only returns errors due to context cancelation. If no context is associated the the Group, wait never returns an error.
Once Wait is called, any further calls to Delay or Schedule will panic. If Wait is called more than once, Wait will panic.