fix batch code comments

Author: roseduan

segment.go

@@ -180,16 +180,21 @@ func (seg *segment) writeToBuffer(data []byte, chunkBuffer *bytebufferpool.ByteB
 		return nil, ErrClosed
 	}
 
+	// if the left block size can not hold the chunk header, padding the block
 	if seg.currentBlockSize+chunkHeaderSize >= blockSize {
 		// padding if necessary
 		if seg.currentBlockSize < blockSize {
-			chunkBuffer.Write(make([]byte, blockSize-seg.currentBlockSize))
+			p := make([]byte, blockSize-seg.currentBlockSize)
+			chunkBuffer.B = append(chunkBuffer.B, p...)
 			padding += blockSize - seg.currentBlockSize
+
+			// a new block
 			seg.currentBlockNumber += 1
 			seg.currentBlockSize = 0
 		}
-
 	}
+
+	// return the start position of the chunk, for reading.
 	position := &ChunkPosition{
 		SegmentId:   seg.id,
 		BlockNumber: seg.currentBlockNumber,
@@ -240,9 +245,12 @@ func (seg *segment) writeToBuffer(data []byte, chunkBuffer *bytebufferpool.ByteB
 
 		position.ChunkSize = blockCount*chunkHeaderSize + dataSize
 	}
+
+	// the buffer length must be equal to chunkSize+padding length
 	endLen := chunkBuffer.Len()
 	if position.ChunkSize+padding != uint32(endLen-startLen) {
-		panic(fmt.Sprintf("chunk size %d, len %d", position.ChunkSize, endLen-startLen-int(padding)))
+		panic(fmt.Sprintf("wrong!!! the chunk size %d is not equal to the buffer len %d",
+			position.ChunkSize+padding, endLen-startLen))
 	}
 
 	// update segment status
@@ -261,6 +269,7 @@ func (seg *segment) writeAll(data [][]byte) (positions []*ChunkPosition, err err
 		return nil, ErrClosed
 	}
 
+	// if any error occurs, restore the segment status
 	originBlockNumber := seg.currentBlockNumber
 	originBlockSize := seg.currentBlockSize
 
@@ -276,6 +285,7 @@ func (seg *segment) writeAll(data [][]byte) (positions []*ChunkPosition, err err
 		bytebufferpool.Put(chunkBuffer)
 	}()
 
+	// write all data to the chunk buffer
 	var pos *ChunkPosition
 	positions = make([]*ChunkPosition, len(data))
 	for i := 0; i < len(positions); i++ {
@@ -285,6 +295,7 @@ func (seg *segment) writeAll(data [][]byte) (positions []*ChunkPosition, err err
 		}
 		positions[i] = pos
 	}
+	// write the chunk buffer to the segment file
 	if err = seg.writeChunkBuffer(chunkBuffer); err != nil {
 		return
 	}

wal.go

@@ -310,7 +310,8 @@ func (wal *WAL) ClearPendingWrites() {
 }
 
 // PendingWrites add data to wal.pendingWrites and wait for batch write.
-// If the data in pendingWrites exceeds the size of one segment, it will return a 'ErrPendingSizeTooLarge' error and clear the pendingWrites
+// If the data in pendingWrites exceeds the size of one segment,
+// it will return a 'ErrPendingSizeTooLarge' error and clear the pendingWrites.
 func (wal *WAL) PendingWrites(data []byte) error {
 	wal.pendingWritesLock.Lock()
 	defer wal.pendingWritesLock.Unlock()
@@ -326,8 +327,8 @@ func (wal *WAL) PendingWrites(data []byte) error {
 	return nil
 }
 
-// flushActiveSegment create a new segment file and replace the activeSegment.
-func (wal *WAL) flushActiveSegment() error {
+// rotateActiveSegment create a new segment file and replace the activeSegment.
+func (wal *WAL) rotateActiveSegment() error {
 	if err := wal.activeSegment.Sync(); err != nil {
 		return err
 	}
@@ -354,17 +355,20 @@ func (wal *WAL) WriteAll() ([]*ChunkPosition, error) {
 		wal.mu.Unlock()
 	}()
 
+	// if the active segment file is full, sync it and create a new one.
 	if wal.activeSegment.Size()+wal.pendingSize > wal.options.SegmentSize {
-		if err := wal.flushActiveSegment(); err != nil {
+		if err := wal.rotateActiveSegment(); err != nil {
 			return nil, err
 		}
 	}
 
+	// write all data to the active segment file.
 	positions, err := wal.activeSegment.writeAll(wal.pendingWrites)
 	if err != nil {
 		return nil, err
 	}
 
+	// sync the active segment file to ensure the durability.
 	if err := wal.activeSegment.Sync(); err != nil {
 		return nil, err
 	}
@@ -383,7 +387,7 @@ func (wal *WAL) Write(data []byte) (*ChunkPosition, error) {
 	}
 	// if the active segment file is full, sync it and create a new one.
 	if wal.isFull(int64(len(data))) {
-		if err := wal.flushActiveSegment(); err != nil {
+		if err := wal.rotateActiveSegment(); err != nil {
 			return nil, err
 		}
 	}

wal_test.go

@@ -331,25 +331,3 @@ func TestWAL_RenameFileExt(t *testing.T) {
 		assert.Nil(t, err)
 	}
 }
-
-func TestWAL_calSizeUpperBound(t *testing.T) {
-	dir, _ := os.MkdirTemp("", "wal-test-TestWAL_calSizeUpperBound")
-	opts := Options{
-		DirPath:        dir,
-		SegmentFileExt: ".VLOG.1.temp",
-		SegmentSize:    8 * 1024 * 1024,
-		BlockCache:     32 * KB * 10,
-	}
-	wal, err := Open(opts)
-	assert.Nil(t, err)
-	defer destroyWAL(wal)
-
-	size := wal.maxDataWriteSize(int64(0))
-	assert.Equal(t, int64(14), size)
-
-	size = wal.maxDataWriteSize(int64(32761))
-	assert.Equal(t, int64(32775), size)
-
-	size = wal.maxDataWriteSize(int64(32769))
-	assert.Equal(t, int64(32790), size)
-}