Merge pull request #72 from sourcegraph/pool-withcontext-docstrings

pool: update docstrings on WithContext
sourcegraph · Jan 17, 2023 · ee6e48f · ee6e48f
2 parents c2e0a60 + 16e8a3d
commit ee6e48f
Show file tree

Hide file tree

Showing 4 changed files with 13 additions and 5 deletions.
diff --git a/pool/error_pool.go b/pool/error_pool.go
@@ -36,7 +36,9 @@ func (p *ErrorPool) Wait() error {
 }
 
 // WithContext converts the pool to a ContextPool for tasks that should
-// be canceled on first error.
+// run under the same context, such that they each respect shared cancellation.
+// For example, WithCancelOnError can be configured on the returned pool to
+// signal that all goroutines should be cancelled upon the first error.
 func (p *ErrorPool) WithContext(ctx context.Context) *ContextPool {
 	ctx, cancel := context.WithCancel(ctx)
 	return &ContextPool{

diff --git a/pool/pool.go b/pool/pool.go
@@ -116,7 +116,9 @@ func (p *Pool) deref() Pool {
 }
 
 // WithContext converts the pool to a ContextPool for tasks that should
-// be canceled on first error.
+// run under the same context, such that they each respect shared cancellation.
+// For example, WithCancelOnError can be configured on the returned pool to
+// signal that all goroutines should be cancelled upon the first error.
 func (p *Pool) WithContext(ctx context.Context) *ContextPool {
 	ctx, cancel := context.WithCancel(ctx)
 	return &ContextPool{

diff --git a/pool/result_error_pool.go b/pool/result_error_pool.go
@@ -45,7 +45,9 @@ func (p *ResultErrorPool[T]) WithCollectErrored() *ResultErrorPool[T] {
 }
 
 // WithContext converts the pool to a ResultContextPool for tasks that should
-// be canceled on first error.
+// run under the same context, such that they each respect shared cancellation.
+// For example, WithCancelOnError can be configured on the returned pool to
+// signal that all goroutines should be cancelled upon the first error.
 func (p *ResultErrorPool[T]) WithContext(ctx context.Context) *ResultContextPool[T] {
 	return &ResultContextPool[T]{
 		contextPool: *p.errorPool.WithContext(ctx),

diff --git a/pool/result_pool.go b/pool/result_pool.go
@@ -52,8 +52,10 @@ func (p *ResultPool[T]) WithErrors() *ResultErrorPool[T] {
 	}
 }
 
-// WithContext converts the pool to a ContextPool for tasks that should be
-// canceled on first error.
+// WithContext converts the pool to a ResultContextPool for tasks that should
+// run under the same context, such that they each respect shared cancellation.
+// For example, WithCancelOnError can be configured on the returned pool to
+// signal that all goroutines should be cancelled upon the first error.
 func (p *ResultPool[T]) WithContext(ctx context.Context) *ResultContextPool[T] {
 	return &ResultContextPool[T]{
 		contextPool: *p.pool.WithContext(ctx),