diff --git a/example_test.go b/example_test.go index 1f613ee..1386f68 100644 --- a/example_test.go +++ b/example_test.go @@ -148,7 +148,7 @@ func ExampleDurationRandomJob() { ) } -func ExampleJob_ID() { +func ExampleJob_id() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -164,7 +164,7 @@ func ExampleJob_ID() { fmt.Println(j.ID()) } -func ExampleJob_LastRun() { +func ExampleJob_lastRun() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -180,7 +180,26 @@ func ExampleJob_LastRun() { fmt.Println(j.LastRun()) } -func ExampleJob_NextRun() { +func ExampleJob_name() { + s, _ := NewScheduler() + defer func() { _ = s.Shutdown() }() + + j, _ := s.NewJob( + DurationJob( + time.Second, + ), + NewTask( + func() {}, + ), + WithName("foobar"), + ) + + fmt.Println(j.Name()) + // Output: + // foobar +} + +func ExampleJob_nextRun() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -196,7 +215,7 @@ func ExampleJob_NextRun() { fmt.Println(j.NextRun()) } -func ExampleJob_RunNow() { +func ExampleJob_runNow() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -218,6 +237,25 @@ func ExampleJob_RunNow() { _ = j.RunNow() } +func ExampleJob_tags() { + s, _ := NewScheduler() + defer func() { _ = s.Shutdown() }() + + j, _ := s.NewJob( + DurationJob( + time.Second, + ), + NewTask( + func() {}, + ), + WithTags("foo", "bar"), + ) + + fmt.Println(j.Tags()) + // Output: + // [foo bar] +} + func ExampleMonthlyJob() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -270,7 +308,24 @@ func ExampleOneTimeJob() { s.Start() } -func ExampleScheduler_NewJob() { +func ExampleScheduler_jobs() { + s, _ := NewScheduler() + defer func() { _ = s.Shutdown() }() + + _, _ = s.NewJob( + DurationJob( + 10*time.Second, + ), + NewTask( + func() {}, + ), + ) + fmt.Println(len(s.Jobs())) + // Output: + // 1 +} + +func ExampleScheduler_newJob() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -288,7 +343,7 @@ func ExampleScheduler_NewJob() { fmt.Println(j.ID()) } -func ExampleScheduler_RemoveByTags() { +func ExampleScheduler_removeByTags() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -322,7 +377,7 @@ func ExampleScheduler_RemoveByTags() { // 0 } -func ExampleScheduler_RemoveJob() { +func ExampleScheduler_removeJob() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -346,7 +401,7 @@ func ExampleScheduler_RemoveJob() { // 0 } -func ExampleScheduler_Start() { +func ExampleScheduler_start() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -363,7 +418,7 @@ func ExampleScheduler_Start() { s.Start() } -func ExampleScheduler_StopJobs() { +func ExampleScheduler_stopJobs() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() @@ -382,7 +437,12 @@ func ExampleScheduler_StopJobs() { _ = s.StopJobs() } -func ExampleScheduler_Update() { +func ExampleScheduler_shutdown() { + s, _ := NewScheduler() + defer func() { _ = s.Shutdown() }() +} + +func ExampleScheduler_update() { s, _ := NewScheduler() defer func() { _ = s.Shutdown() }() diff --git a/job.go b/job.go index 9d76501..d25cab4 100644 --- a/job.go +++ b/job.go @@ -831,12 +831,20 @@ func (o oneTimeJob) next(_ time.Time) time.Time { // Job provides the available methods on the job // available to the caller. type Job interface { + // ID returns the job's unique identifier. ID() uuid.UUID + // LastRun returns the time of the job's last run LastRun() (time.Time, error) + // Name returns the name defined on the job. Name() string + // NextRun returns the time of the job's next scheduled run. NextRun() (time.Time, error) - Tags() []string + // RunNow runs the job once, now. This does not alter + // the existing run schedule, and will respect all job + // and scheduler limits. RunNow() error + // Tags returns the job's string tags. + Tags() []string } var _ Job = (*job)(nil) @@ -853,12 +861,10 @@ type job struct { runJobRequest chan runJobRequest } -// ID returns the job's unique identifier. func (j job) ID() uuid.UUID { return j.id } -// LastRun returns the time of the job's last run func (j job) LastRun() (time.Time, error) { ij := requestJob(j.id, j.jobOutRequest) if ij == nil || ij.id == uuid.Nil { @@ -867,12 +873,10 @@ func (j job) LastRun() (time.Time, error) { return ij.lastRun, nil } -// Name returns the name defined on the job. func (j job) Name() string { return j.name } -// NextRun returns the time of the job's next scheduled run. func (j job) NextRun() (time.Time, error) { ij := requestJob(j.id, j.jobOutRequest) if ij == nil || ij.id == uuid.Nil { @@ -881,14 +885,10 @@ func (j job) NextRun() (time.Time, error) { return ij.nextRun, nil } -// Tags returns the job's string tags. func (j job) Tags() []string { return j.tags } -// RunNow runs the job once, now. This does not alter -// the existing run schedule, and will respect all job -// and scheduler limits. func (j job) RunNow() error { ctx, cancel := context.WithTimeout(context.Background(), time.Second) defer cancel() diff --git a/scheduler.go b/scheduler.go index 6edaf4e..f5c7d26 100644 --- a/scheduler.go +++ b/scheduler.go @@ -16,14 +16,22 @@ var _ Scheduler = (*scheduler)(nil) // Scheduler defines the interface for the Scheduler. type Scheduler interface { - // Jobs returns a list of all jobs in the scheduler. + // Jobs returns all the jobs currently in the scheduler. Jobs() []Job - // NewJob creates a new Job and adds it to the Scheduler. + // NewJob creates a new job in the Scheduler. The job is scheduled per the provided + // definition when the Scheduler is started. If the Scheduler is already running + // the job will be scheduled when the Scheduler is started. NewJob(JobDefinition, Task, ...JobOption) (Job, error) - // RemoveByTags removes all jobs matching the provided tags. + // RemoveByTags removes all jobs that have at least one of the provided tags. RemoveByTags(...string) // RemoveJob removes the job with the provided id. RemoveJob(uuid.UUID) error + // Shutdown should be called when you no longer need + // the Scheduler or Job's as the Scheduler cannot + // be restarted after calling Shutdown. This is similar + // to a Close or Cleanup method and is often deferred after + // starting the scheduler. + Shutdown() error // Start begins scheduling jobs for execution based // on each job's definition. Job's added to an already // running scheduler will be scheduled immediately based @@ -33,12 +41,6 @@ type Scheduler interface { // This can be useful in situations where jobs need to be // paused globally and then restarted with Start(). StopJobs() error - // Shutdown should be called when you no longer need - // the Scheduler or Job's as the Scheduler cannot - // be restarted after calling Shutdown. This is similar - // to a Close or Cleanup method and is often deferred after - // starting the scheduler. - Shutdown() error // Update replaces the existing Job's JobDefinition with the provided // JobDefinition. The Job's Job.ID() remains the same. Update(uuid.UUID, JobDefinition, Task, ...JobOption) (Job, error)