added tests and docs

Author: hedzr

mpmc/rb.go

@@ -11,8 +11,8 @@ import (
 
 // New returns the RingBuffer object.
 //
-// It returns ErrQueueFull when the queue is full and
-// putting a new element.
+// It returns [ErrQueueFull] when you're trying to put a new
+// element into a full ring buffer.
 func New[T any](capacity uint32, opts ...Opt[T]) (ringBuffer RingBuffer[T]) {
 	return newRingBuffer(func(capacity uint32, opts ...Opt[T]) (ringBuffer RingBuffer[T]) {
 		size := roundUpToPower2(capacity)
@@ -29,8 +29,17 @@ func New[T any](capacity uint32, opts ...Opt[T]) (ringBuffer RingBuffer[T]) {
 	}, capacity, opts...)
 }
 
-// NewOverlappedRingBuffer initials a ring buffer, which overwrites
-// its head element if it's full.
+// NewOverlappedRingBuffer make a new instance of the overlapped ring
+// buffer, which overwrites its head element if it's full.
+//
+// When an unexpected state occurred, the returned value could be nil.
+//
+// In this case, checking it for unavailable value is recommended.
+// This could happen if a physical core fault detected in high-freq,
+// high-pressure, and high-temperature place.
+//
+// For the normal runtime environment, unexpected state should be
+// impossible, so ignore it is safe.
 func NewOverlappedRingBuffer[T any](capacity uint32, opts ...Opt[T]) (ringBuffer RingBuffer[T]) {
 	return newRingBuffer(func(capacity uint32, opts ...Opt[T]) (ringBuffer RingBuffer[T]) {
 		size := roundUpToPower2(capacity)
@@ -49,28 +58,12 @@ func NewOverlappedRingBuffer[T any](capacity uint32, opts ...Opt[T]) (ringBuffer
 	}, capacity, opts...)
 }
 
+// Creator _
 type Creator[T any] func(capacity uint32, opts ...Opt[T]) (ringBuffer RingBuffer[T])
 
 func newRingBuffer[T any](creator Creator[T], capacity uint32, opts ...Opt[T]) (ringBuffer RingBuffer[T]) {
 	if isInitialized() {
 		ringBuffer = creator(capacity, opts...)
-
-		// ringBuffer = rb
-
-		// for _, opt := range opts {
-		// 	opt(rb)
-		// }
-
-		// // if rb.debugMode && rb.logger != nil {
-		// //	// rb.logger.Debug("[ringbuf][INI] ", zap.Uint32("cap", rb.cap), zap.Uint32("capModMask", rb.capModMask))
-		// // }
-
-		// for i := 0; i < int(size); i++ {
-		// 	rb.data[i].readWrite &= 0 // bit 0: readable, bit 1: writable
-		// 	if rb.initializer != nil {
-		// 		rb.data[i].value = rb.initializer.PreAlloc(i)
-		// 	}
-		// }
 	}
 	return
 }

mpmc/rb2_test.go

@@ -77,3 +77,98 @@ func TestOverlappedRingBuf_Put_OneByOne(t *testing.T) { //nolint:revive
 		t.Fatalf("faild: Dequeue on an empty ringbuf should return an ErrQueueEmpty object.")
 	}
 }
+
+func TestOverlappedRingBuf_Random(t *testing.T) { //nolint:revive
+	var err error
+	var i uint32
+	rb := NewOverlappedRingBuffer(NLtd, WithDebugMode[uint32](true))
+	size := rb.Cap() - 1
+	// t.Logf("Ring Buffer created, capacity = %v, real size: %v", size+1, size)
+	defer rb.Close()
+
+	for ; i < size; i++ {
+		err = rb.Enqueue(i)
+		if err != nil {
+			t.Fatalf("faild on i=%v. err: %+v", i, err)
+			// } else {
+			// t.Logf("%5d. '%v' put, quantity = %v.", i, i, fast.Quantity())
+		}
+		t.Logf("  %3d. ringbuf elements -> %v", i, rb)
+	}
+
+	for ; i < size+size; i++ {
+		err = rb.Put(i)
+		if errors.Is(err, ErrQueueFull) {
+			t.Fatalf("> %3d. expect ErrQueueFull but no error raised. err: %+v", i, err)
+		}
+		t.Logf("  %3d. ringbuf elements -> %v", i, rb)
+	}
+
+	t.Log("remove 2 elems.")
+
+	var it any
+	it, err = rb.Dequeue()
+	_, _ = it, err
+	t.Logf("  %3d. ringbuf elements -> %v", i, rb)
+	i++
+	it, err = rb.Dequeue()
+	_, _ = it, err
+	t.Logf("  %3d. ringbuf elements -> %v", i, rb)
+	i++
+	if fmt.Sprintf("%v", rb) != "[17,18,19,20,21,22,23,24,25,26,27,28,29,]/13" {
+		t.Fatalf("faild: expecting elements are: [17,18,19,20,21,22,23,24,25,26,27,28,29,]/13")
+	}
+
+	t.Logf("removed 2 elems, and inserting some new...")
+
+	for ; i < size*2+8; i++ {
+		err = rb.Put(i)
+		if errors.Is(err, ErrQueueFull) {
+			t.Fatalf("> %3d. expect ErrQueueFull but no error raised. err: %+v", i, err)
+		}
+		t.Logf("  %3d. ringbuf elements -> %v", i, rb)
+	}
+
+	it, err = rb.Dequeue()
+	_, _ = it, err
+	t.Logf("removed 1 elem: %v", it)
+	t.Logf("  %3d. ringbuf elements -> %v", i, rb)
+	i++
+
+	for ; i < size*3+3; i++ {
+		err = rb.Put(i)
+		if errors.Is(err, ErrQueueFull) {
+			t.Fatalf("> %3d. expect ErrQueueFull but no error raised. err: %+v", i, err)
+		}
+		t.Logf("  %3d. ringbuf elements -> %v", i, rb)
+	}
+	if fmt.Sprintf("%v", rb) != "[32,33,34,35,36,37,39,40,41,42,43,44,45,46,47,]/15" {
+		t.Fatalf("faild: expecting elements are: [32,33,34,35,36,37,39,40,41,42,43,44,45,46,47,]/15")
+	}
+
+	// cleanup
+
+	for i := 0; ; i++ {
+		it, err = rb.Dequeue()
+		if err != nil {
+			if errors.Is(err, ErrQueueEmpty) {
+				break
+			}
+			t.Fatalf("faild on i=%v. err: %+v. item: %v", i, err, it)
+			// } else {
+			// t.Logf("< %3d. '%v' GOT, quantity = %v.", i, it, fast.Quantity())
+		}
+		if rb.Size() == 0 {
+			// t.Log("empty ring buffer elements")
+			if fmt.Sprintf("%v", rb) != "[]/0" {
+				t.Fatalf("faild: expecting elements are: []/0")
+			}
+		}
+		t.Logf("  %3d. ringbuf elements -> %v", i, rb)
+	}
+
+	it, err = rb.Dequeue()
+	if err == nil {
+		t.Fatalf("faild: Dequeue on an empty ringbuf should return an ErrQueueEmpty object.")
+	}
+}