wal

README

WAL (Write ahead log)

wal is a write ahead log written in go.

Installation

The code was tested with go version 1.15. Older versions can also work but have not been tested.

go get -u github.com/ljmsc/wal

Currently, only unix systems are supported.

Usage

Note: since version 0.7.0 the wal is no longer safe for concurrent write. It is up to the developer to protect the wal. e.g. Mutex, Channels. Since this kind of functionality is not always needed I removed it for performance's sake.

basic

package main

import (
	"fmt"

	"github.com/ljmsc/wal"
)

type entry []byte

func (t *entry) Unmarshal(_data []byte) error {
	*t = _data
	return nil
}

func main() {
	storage, err := wal.Open("./path/to/wal", 4, 100)
	if err != nil {
		// handle error
		panic(err)
	}
	defer storage.Close()

	data := []byte("this is my awesome test data")
	seqNum, err := storage.Write(data)
	if err != nil {
		// handle write error
		panic(err)
	}
	fmt.Printf("successful wrote entry. Sequence Number: %d\n", seqNum)

	re := entry{}
	if err := storage.ReadAt(&re, seqNum); err != nil {
		// handle error
		panic(err)
	}

	fmt.Printf("successful read entry from log. value: %s \n", re)
}

License

The project (and all code) is licensed under the Mozilla Public License Version 2.0.

Documentation

Index

• Variables
• type Entry
• type Envelope
• type Wal
  • func Open(_name string, _segBlockN int64, _segSize int64) (Wal, error)

Variables

var (
	ErrNoData           = fmt.Errorf("no data provided")
	ErrEntryNotFound    = fmt.Errorf("entry not found")
	ErrSeqNumOutOfRange = fmt.Errorf("sequence number is out of range")
)

Types

type Entry

type Entry interface {
	Unmarshal(_data []byte) error
}

type Envelope

type Envelope struct {
	SeqNum  uint64
	Payload []byte
	Err     error
}

type Wal

type Wal interface {
	// Name returns the name of the write ahead log
	Name() string
	// Read reads the data of the entry with the given sequence number and returns it
	Read(_seqNum uint64) ([]byte, error)
	// ReadAt reads the data of the entry with the given sequence number to _entry
	// Deprecated
	ReadAt(_entry Entry, _seqNum uint64) error
	// ReadTo reads the data of the entry with the given sequence number to _entry
	ReadTo(_entry encoding.BinaryUnmarshaler, _seqNum uint64) error
	// ReadFrom reads the payload of _n entries starting from _seqNum
	ReadFrom(_seqNum uint64, _n int64) (<-chan Envelope, error)
	// Write writes the given data on disk and returns the new sequence number
	Write(_data []byte) (uint64, error)
	// WriteFrom extracts data from the given object and writes it on disk. it returns the new sequence number
	WriteFrom(r encoding.BinaryMarshaler) (uint64, error)
	// Truncate dumps all records whose sequence number is greater or equal to offsetByPos
	Truncate(_seqNum uint64) error
	// Sync flushes changes to persistent storage and returns the latest safe sequence number
	Sync() (uint64, error)
	// First returns the first sequence number in the write ahead log
	First() uint64
	// SeqNum returns the latest written sequence number in the write ahead log
	SeqNum() uint64
	// Safe returns the latest safe sequence number
	Safe() uint64
	// Close closes the write ahead log and all segment files
	Close() error
}

func Open

func Open(_name string, _segBlockN int64, _segSize int64) (Wal, error)

Open opens or creates a write ahead log. _segBlockN is the amount of records which can be written to a single filesystem page _segSize is the amount of records which can be written to the segment file