doc

Author: RangelReale

README.md

@@ -18,7 +18,7 @@ import (
     "github.com/rrgmc/nbchanlist"
 )
 
-func ExampleQueue() {
+func ExampleNewQueue() {
     q := nbchanlist.NewQueue[int]()
     q.Put(12) // never blocks
     q.Put(13)
@@ -37,6 +37,10 @@ func ExampleQueue() {
             fmt.Println("should never happen")
         }
     }
+
+    // Output:
+    // 12
+    // queue is closed
 }
 ```
 

example_test.go

@@ -26,4 +26,8 @@ func ExampleNewQueue() {
 			fmt.Println("should never happen")
 		}
 	}
+
+	// Output:
+	// 12
+	// queue is closed
 }

list.go

@@ -7,7 +7,7 @@ import (
 )
 
 var (
-	ErrClosed = errors.New("list is closed")
+	ErrStopped = errors.New("stopped")
 )
 
 // List is a non-blocking unbounded lock-free channel-based list for Golang.
@@ -28,11 +28,13 @@ func New[E any, Q ListType[E]](list Q) *List[E, Q] {
 }
 
 // Get returns a channel to get items. The caller must check for it to be closed.
+// It can still be called even after Stop.
 func (q *List[E, Q]) Get() <-chan E {
 	return q.out
 }
 
 // GetCtx returns one item, or an error if the context is done or the list is closed.
+// It can still be called even after Stop.
 func (q *List[E, Q]) GetCtx(ctx context.Context) (E, error) {
 	select {
 	case <-ctx.Done():
@@ -41,7 +43,7 @@ func (q *List[E, Q]) GetCtx(ctx context.Context) (E, error) {
 	case v, ok := <-q.Get():
 		if !ok {
 			var ret E
-			return ret, ErrClosed
+			return ret, ErrStopped
 		}
 		return v, nil
 	}
@@ -53,13 +55,13 @@ func (q *List[E, Q]) Put(e E) {
 }
 
 // PutCheck puts an element in the list. It never fails or blocks.
-// Returns ErrClosed if the list is closed.
+// Returns ErrStopped if the list stopped accepting new items.
 func (q *List[E, Q]) PutCheck(e E) error {
 	if in := q.in.Load(); in != nil {
 		*in <- e
 		return nil
 	}
-	return ErrClosed
+	return ErrStopped
 }
 
 func (q *List[E, Q]) Size() int {
@@ -72,12 +74,21 @@ func (q *List[E, Q]) Size() int {
 	}
 }
 
-func (q *List[E, Q]) Closed() bool {
+func (q *List[E, Q]) Stopped() bool {
 	return q.in.Load() == nil
 }
 
+// Stop stops accepting new items. Get still works until the list is drained.
+func (q *List[E, Q]) Stop() {
+	if in := q.in.Swap(nil); in != nil {
+		close(*in)
+	}
+}
+
+// Close stops accepting new items and drains any existing ones, freeing all used resources.
 func (q *List[E, Q]) Close() {
-	if old := q.in.Swap(nil); old != nil {
-		close(*old)
+	q.Stop()
+	// drain items to stop goroutine.
+	for range q.out {
 	}
 }

queue_test.go

@@ -32,17 +32,17 @@ func TestQueueCtx(t *testing.T) {
 	assert.Equal(t, q.Size(), 0)
 }
 
-func TestQueueClose(t *testing.T) {
+func TestQueueStop(t *testing.T) {
 	q := NewQueue[int]()
 	q.Put(12)
 	q.Put(13)
-	q.Close()
+	q.Stop()
 	q.Put(16)
-	assert.Assert(t, q.Closed())
+	assert.Assert(t, q.Stopped())
 	expected := []int{12, 13}
-	items, err := readNWithTimeout(q, 3)
-	assert.ErrorIs(t, err, ErrClosed)
-	assert.DeepEqual(t, expected, items)
+	items, err := readNWithTimeout(q, 3) // can still Get after Stop.
+	assert.ErrorIs(t, err, ErrStopped)
+	assert.DeepEqual(t, expected, items) // still gets the expected items.
 }
 
 func TestQueueTimeout(t *testing.T) {
@@ -55,6 +55,19 @@ func TestQueueTimeout(t *testing.T) {
 	assert.DeepEqual(t, expected, items)
 }
 
+func TestQueueClose(t *testing.T) {
+	q := NewQueue[int]()
+	q.Put(12)
+	q.Put(13)
+	q.Close()
+	q.Put(16)
+	assert.Assert(t, q.Stopped())
+	var expected []int                   // Close drains all pending items.
+	items, err := readNWithTimeout(q, 2) // can still get after close
+	assert.ErrorIs(t, err, ErrStopped)
+	assert.DeepEqual(t, expected, items)
+}
+
 func TestQueueCtxTimeout(t *testing.T) {
 	ctx := context.Background()
 	q := NewQueue[int]()
@@ -98,8 +111,9 @@ func TestQueueConcurrency(t *testing.T) {
 		}()
 	}
 	wgPut.Wait()
-	q.Close()
+	q.Stop()
 	wgGet.Wait()
+	q.Close()
 
 	assert.Assert(t, cmp2.Len(putItems, 10*10))
 	assert.Assert(t, cmp2.Len(getItems, 10*10))
@@ -147,7 +161,7 @@ func readNWithTimeout[E any, Q ListType[E]](q *List[E, Q], n int) ([]E, error) {
 		select {
 		case item, ok := <-q.Get():
 			if !ok {
-				return ret, ErrClosed
+				return ret, ErrStopped
 			}
 			ret = append(ret, item)
 		case <-time.After(300 * time.Millisecond):