From 27383ed92954385652270a3293a267c02747ab96 Mon Sep 17 00:00:00 2001 From: Blake Gentry Date: Tue, 16 Jan 2024 09:37:42 -0600 Subject: [PATCH] rename Client.Cancel to Client.JobCancel This was added in #141 / 0aaeee8. Meanwhile another job-related query API was added called `JobList`, but `Cancel` and `CancelTx` were not given the `Job*` prefix. This renames `Cancel` to `JobCancel` and `CancelTx` to `JobCancelTx` for consistency. Other upcoming job query APIs will also use the prefix. --- CHANGELOG.md | 2 +- client.go | 21 ++++++++++--------- client_test.go | 10 ++++----- ... => example_job_cancel_from_client_test.go | 8 +++---- 4 files changed, 21 insertions(+), 20 deletions(-) rename example_cancel_from_client_test.go => example_job_cancel_from_client_test.go (92%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 972c474a..b0a7e8ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Added `Cancel` and `CancelTx` to the `Client` to enable cancellation of jobs. [PR #141](https://github.com/riverqueue/river/pull/141). +- Added `JobCancel` and `JobCancelTx` to the `Client` to enable cancellation of jobs. [PR #141](https://github.com/riverqueue/river/pull/141). - Added `ClientFromContext` and `ClientWithContextSafely` helpers to extract the `Client` from the worker's context where it is now available to workers. This simplifies making the River client available within your workers for i.e. enqueueing additional jobs. [PR #145](https://github.com/riverqueue/river/pull/145). - Add `JobList` API for listing jobs. [PR #117](https://github.com/riverqueue/river/pull/117). diff --git a/client.go b/client.go index 3a1c82c1..bc18bb50 100644 --- a/client.go +++ b/client.go @@ -940,10 +940,10 @@ func (c *Client[TTx]) runProducers(fetchNewWorkCtx, workCtx context.Context) { } } -// Cancel cancels the job with the given ID. If possible, the job is cancelled -// immediately and will not be retried. The provided context is used for the -// underlying Postgres update and can be used to cancel the operation or apply a -// timeout. +// JobCancel cancels the job with the given ID. If possible, the job is +// cancelled immediately and will not be retried. The provided context is used +// for the underlying Postgres update and can be used to cancel the operation or +// apply a timeout. // // If the job is still in the queue (available, scheduled, or retryable), it is // immediately marked as cancelled and will not be retried. @@ -976,7 +976,7 @@ func (c *Client[TTx]) runProducers(fetchNewWorkCtx, workCtx context.Context) { // // Returns the up-to-date JobRow for the specified jobID if it exists. Returns // ErrNotFound if the job doesn't exist. -func (c *Client[TTx]) Cancel(ctx context.Context, jobID int64) (*rivertype.JobRow, error) { +func (c *Client[TTx]) JobCancel(ctx context.Context, jobID int64) (*rivertype.JobRow, error) { job, err := c.adapter.JobCancel(ctx, jobID) if err != nil { if errors.Is(err, riverdriver.ErrNoRows) { @@ -988,10 +988,11 @@ func (c *Client[TTx]) Cancel(ctx context.Context, jobID int64) (*rivertype.JobRo return dbsqlc.JobRowFromInternal(job), nil } -// CancelTx cancels the job with the given ID within the specified transaction. -// This variant lets a caller cancel a job atomically alongside other database -// changes. An cancelled job doesn't take effect until the transaction commits, -// and if the transaction rolls back, so too is the cancelled job. +// JobCancelTx cancels the job with the given ID within the specified +// transaction. This variant lets a caller cancel a job atomically alongside +// other database changes. An cancelled job doesn't take effect until the +// transaction commits, and if the transaction rolls back, so too is the +// cancelled job. // // If possible, the job is cancelled immediately and will not be retried. The // provided context is used for the underlying Postgres update and can be used @@ -1028,7 +1029,7 @@ func (c *Client[TTx]) Cancel(ctx context.Context, jobID int64) (*rivertype.JobRo // // Returns the up-to-date JobRow for the specified jobID if it exists. Returns // ErrNotFound if the job doesn't exist. -func (c *Client[TTx]) CancelTx(ctx context.Context, tx TTx, jobID int64) (*rivertype.JobRow, error) { +func (c *Client[TTx]) JobCancelTx(ctx context.Context, tx TTx, jobID int64) (*rivertype.JobRow, error) { job, err := c.adapter.JobCancelTx(ctx, c.driver.UnwrapTx(tx), jobID) if errors.Is(err, riverdriver.ErrNoRows) { return nil, ErrNotFound diff --git a/client_test.go b/client_test.go index a4024fc6..753f1949 100644 --- a/client_test.go +++ b/client_test.go @@ -326,7 +326,7 @@ func Test_Client(t *testing.T) { t.Parallel() cancelRunningJobTestHelper(t, func(ctx context.Context, client *Client[pgx.Tx], jobID int64) (*rivertype.JobRow, error) { - return client.Cancel(ctx, jobID) + return client.JobCancel(ctx, jobID) }) }) @@ -339,7 +339,7 @@ func Test_Client(t *testing.T) { err error ) txErr := pgx.BeginFunc(ctx, client.driver.GetDBPool(), func(tx pgx.Tx) error { - job, err = client.CancelTx(ctx, tx, jobID) + job, err = client.JobCancelTx(ctx, tx, jobID) return err }) require.NoError(t, txErr) @@ -370,7 +370,7 @@ func Test_Client(t *testing.T) { require.NoError(t, err) // Cancel the job: - updatedJob, err := client.Cancel(ctx, insertedJob.ID) + updatedJob, err := client.JobCancel(ctx, insertedJob.ID) require.NoError(t, err) require.NotNil(t, updatedJob) require.Equal(t, rivertype.JobStateCancelled, updatedJob.State) @@ -384,13 +384,13 @@ func Test_Client(t *testing.T) { startClient(ctx, t, client) // Cancel an unknown job ID: - jobAfter, err := client.Cancel(ctx, 0) + jobAfter, err := client.JobCancel(ctx, 0) require.ErrorIs(t, err, ErrNotFound) require.Nil(t, jobAfter) // Cancel an unknown job ID, within a transaction: err = pgx.BeginFunc(ctx, client.driver.GetDBPool(), func(tx pgx.Tx) error { - jobAfter, err := client.CancelTx(ctx, tx, 0) + jobAfter, err := client.JobCancelTx(ctx, tx, 0) require.ErrorIs(t, err, ErrNotFound) require.Nil(t, jobAfter) return nil diff --git a/example_cancel_from_client_test.go b/example_job_cancel_from_client_test.go similarity index 92% rename from example_cancel_from_client_test.go rename to example_job_cancel_from_client_test.go index 7dfa2658..339ca642 100644 --- a/example_cancel_from_client_test.go +++ b/example_job_cancel_from_client_test.go @@ -33,9 +33,9 @@ func (w *SleepingWorker) Work(ctx context.Context, job *river.Job[CancellingArgs return ctx.Err() } -// Example_cancelJobFromClient demonstrates how to permanently cancel a job from -// any Client using Cancel. -func Example_cancelJobFromClient() { +// Example_jobCancelFromClient demonstrates how to permanently cancel a job from +// any Client using JobCancel. +func Example_jobCancelFromClient() { ctx := context.Background() dbPool, err := pgxpool.NewWithConfig(ctx, riverinternaltest.DatabaseConfig("river_testdb_example")) @@ -88,7 +88,7 @@ func Example_cancelJobFromClient() { // cancellation signal. time.Sleep(500 * time.Millisecond) - if _, err = riverClient.Cancel(ctx, job.ID); err != nil { + if _, err = riverClient.JobCancel(ctx, job.ID); err != nil { panic(err) } waitForNJobs(subscribeChan, 1)