raftio

Documentation

Overview

Package raftio contains structs, interfaces and function definitions required to build customized persistent Raft log storage and Raft RPC modules.

Structs, interfaces and functions defined in the raftio package are only required when building your customized persistent Raft log storage or RPC modules. You can safely skip this package if you plan to use the default built-in LogDB and Raft RPC modules provided by Dragonboat.

Index

• Constants
• Variables
• type ChunkSinkFactory
• type IChunkSink
• type IConnection
• type IContext
• type ILogDB
• type IRaftRPC
• type IReusableKey
• type ISnapshotConnection
• type NodeInfo
  • func GetNodeInfo(cid uint64, nid uint64) NodeInfo
• type RaftState
• type RequestHandler

Constants

const (
	// LogDBBinVersion is the current logdb binary compatibility version
	// implemented in Dragonboat.
	// For v1.4  BinVersion = 100
	//     v2.0  BinVersion = 210
	LogDBBinVersion uint32 = 210
	// RPCBinVersion is the RPC binary compatibility version implemented in
	// Dragonboat.
	// For v1.4  RPCBinLog = 100
	//     v2.0  RPCBinLog = 210
	RPCBinVersion uint32 = 210
)

Variables

var (
	// ErrNoSavedLog indicates no saved log.
	ErrNoSavedLog = errors.New("no saved log")
	// ErrNoBootstrapInfo indicates that there is no saved bootstrap info.
	ErrNoBootstrapInfo = errors.New("no bootstrap info")
)

Types

type ChunkSinkFactory

type ChunkSinkFactory func() IChunkSink

ChunkSinkFactory is a factory function that returns a new IChunkSink instance. The returned IChunkSink will be used to accept future received snapshot chunks.

type IChunkSink

type IChunkSink interface {
	// Close closes the sink instance and releases all resources held by it.
	Close()
	// AddChunk adds a new snapshot chunk to the snapshot chunk sink. All chunks
	// belong to the snapshot will be combined into the snapshot image and then
	// be passed to Dragonboat once all member chunks are received.
	AddChunk(chunk pb.SnapshotChunk)
	// Tick moves forward the internal logic clock. It is suppose to be called
	// roughly every second.
	Tick()
}

IChunkSink is the interface of snapshot chunk sink. IChunkSink is used to accept received snapshot chunks.

type IConnection

type IConnection interface {
	// Close closes the IConnection instance.
	Close()
	// SendMessageBatch sends the specified message batch to the target. It is
	// recommended to deliver the message batch to the target in order to enjoy
	// best possible performance, but out of order delivery is allowed at the
	// cost of reduced performance.
	SendMessageBatch(batch pb.MessageBatch) error
}

IConnection is the interface used by the Raft RPC module for sending Raft messages. Each IConnection works for a specified target nodehost instance, it is possible for a target to have multiple concurrent IConnection instances.

type IContext

type IContext interface {
	// Destroy destroys the IContext instance.
	Destroy()
	// Reset resets the IContext instance, all previous returned keys and
	// buffers will be put back to the IContext instance and be ready to
	// be used for the next iteration.
	Reset()
	// GetKey returns a reusable key.
	GetKey() IReusableKey
	// GetValueBuffer returns a byte buffer with at least sz bytes in length.
	GetValueBuffer(sz uint64) []byte
	// GetUpdates return a raftpb.Update slice,
	GetUpdates() []pb.Update
	// GetWriteBatch returns a write batch or transaction instance.
	GetWriteBatch() interface{}
	// GetEntryBatch returns an entry batch instance.
	GetEntryBatch() pb.EntryBatch
	// GetLastEntryBatch returns an entry batch instance.
	GetLastEntryBatch() pb.EntryBatch
}

IContext is the per thread context used in the logdb module. IContext is expected to contain a list of reusable keys and byte slices that are owned per thread so they can be safely reused by the same thread when accessing ILogDB.

type ILogDB

type ILogDB interface {
	// Name returns the type name of the ILogDB instance.
	Name() string
	// Close closes the ILogDB instance.
	Close()
	// GetLogDBThreadContext returns a new IContext instance.
	GetLogDBThreadContext() IContext
	// ListNodeInfo lists all available NodeInfo found in the log DB.
	ListNodeInfo() ([]NodeInfo, error)
	// SaveBootstrapInfo saves the specified bootstrap info to the log DB.
	SaveBootstrapInfo(clusterID uint64,
		nodeID uint64, bootstrap pb.Bootstrap) error
	// GetBootstrapInfo returns saved bootstrap info from log DB. It returns
	// ErrNoBootstrapInfo when there is no previously saved bootstrap info for
	// the specified node.
	GetBootstrapInfo(clusterID uint64, nodeID uint64) (*pb.Bootstrap, error)
	// SaveRaftState atomically saves the Raft states, log entries and snapshots
	// metadata found in the pb.Update list to the log DB.
	SaveRaftState(updates []pb.Update, ctx IContext) error
	// IterateEntries returns the continuous Raft log entries of the specified
	// Raft node between the index value range of [low, high) up to a max size
	// limit of maxSize bytes. It returns the located log entries, their total
	// size in bytes and the occured error.
	IterateEntries(ents []pb.Entry,
		size uint64, clusterID uint64, nodeID uint64, low uint64,
		high uint64, maxSize uint64) ([]pb.Entry, uint64, error)
	// ReadRaftState returns the persistented raft state found in Log DB.
	ReadRaftState(clusterID uint64,
		nodeID uint64, lastIndex uint64) (*RaftState, error)
	// RemoveEntriesTo removes entries associated with the specified Raft node up
	// to the specified index.
	RemoveEntriesTo(clusterID uint64, nodeID uint64, index uint64) error
	// SaveSnapshots saves all snapshot metadata found in the pb.Update list.
	SaveSnapshots([]pb.Update) error
	// DeleteSnapshot removes the specified snapshot metadata from the log DB.
	DeleteSnapshot(clusterID uint64, nodeID uint64, index uint64) error
	// ListSnapshots lists all available snapshots associated with the specified
	// Raft node.
	ListSnapshots(clusterID uint64, nodeID uint64) ([]pb.Snapshot, error)
}

ILogDB is the interface implemented by the log DB for persistently store Raft states, log entries and other Raft metadata.

type IRaftRPC

type IRaftRPC interface {
	// Name returns the type name of the IRaftRPC instance.
	Name() string
	// Start launches the Raft RPC module and make it ready to start sending and
	// receiving Raft messages.
	Start() error
	// Stop stops the Raft RPC instance.
	Stop()
	// GetConnection returns an IConnection instance responsible for
	// sending Raft messages to the specified target nodehost.
	GetConnection(ctx context.Context, target string) (IConnection, error)
	// GetSnapshotConnection returns an ISnapshotConnection instance used for
	// sending snapshot chunks to the specified target nodehost.
	GetSnapshotConnection(ctx context.Context,
		target string) (ISnapshotConnection, error)
}

IRaftRPC is the interface to be implemented by a customized Raft RPC module. A Raft RPC module is responisble for exchanging Raft messages including snapshot chunks between nodehost instances.

type IReusableKey

type IReusableKey interface {
	SetEntryBatchKey(clusterID uint64, nodeID uint64, index uint64)
	// SetEntryKey sets the key to be an entry key for the specified Raft node
	// with the specified entry index.
	SetEntryKey(clusterID uint64, nodeID uint64, index uint64)
	// SetStateKey sets the key to be an persistent state key suitable
	// for the specified Raft cluster node.
	SetStateKey(clusterID uint64, nodeID uint64)
	// SetMaxIndexKey sets the key to be the max possible index key for the
	// specified Raft cluster node.
	SetMaxIndexKey(clusterID uint64, nodeID uint64)
	// Key returns the underlying byte slice of the key.
	Key() []byte
	// Release releases the key instance so it can be reused in the future.
	Release()
}

IReusableKey is the interface for keys that can be reused. A reusable key is usually obtained by calling the GetKey() function of the IContext instance.

type ISnapshotConnection

type ISnapshotConnection interface {
	// Close closes the ISnapshotConnection instance.
	Close()
	// SendSnapshotChunk sends the snapshot chunk to the target. It is
	// recommended to have the snapshot chunk delivered in order for the best
	// performance, but out of order delivery is allowed at the cost of reduced
	// performance.
	SendSnapshotChunk(chunk pb.SnapshotChunk) error
}

ISnapshotConnection is the interface used by the Raft RPC module for sending snapshot chunks. Each ISnapshotConnection works for a specified target nodehost instance.

type NodeInfo

type NodeInfo struct {
	ClusterID uint64
	NodeID    uint64
}

NodeInfo is used to identify a Raft node.

func GetNodeInfo

func GetNodeInfo(cid uint64, nid uint64) NodeInfo

GetNodeInfo returns a NodeInfo instance with the specified cluster ID and node ID.

type RaftState

type RaftState struct {
	// State is the Raft state persistent to the disk
	State *pb.State
	// FirstIndex is the index of the first entry to iterate
	FirstIndex uint64
	// EntryCount is the number of entries to iterate
	EntryCount uint64
}

RaftState is the persistent Raft state found in the Log DB.

type RequestHandler

type RequestHandler func(req pb.MessageBatch)

RequestHandler is the handler function type for handling received message batch. Received message batches should be passed to the request handler to have them processed by Dragonboat.