jrnl

Documentation

Overview

Package jrnl is the top-level journal API.

It provides atomic operations that are buffered locally and manipulate objects via buffers of type *buf.Buf.

The caller uses this interface by beginning an operation Op, reading/writing within the transaction, and finally committing the buffered transaction.

Note that while the API has reads and writes, these are not the usual database read/write transactions. Only writes are made atomic and visible atomically; reads are cached on first read. Thus to use this library the file system in practice locks (sub-block) objects before using them in an operation. This is necessary so that loaded objects are read from a consistent view.

Operations support asynchronous durability by setting wait=false in CommitWait, which results in an "unstable" operation. An unstable operation is made visible atomically to other threads, including across crashes, but if the system crashes the latest unstable operations can be lost. To guarantee that a particular operation is durable, call Flush on the underlying *obj.Log (which flushes all transactions).

Objects have sizes. Implicit in the code is that there is a static "schema" that determines the disk layout: each block has objects of a particular size, and all sizes used fit an integer number of objects in a block. This schema guarantees that objects never overlap, as long as operations involving an addr.Addr use the correct size for that block number.

A file system can realize this schema fairly simply, since the disk is partitioned into inodes, data blocks, and bitmap allocators for each (sized appropriately), all allocated statically.

Index

• Constants
• type Op
  • func Begin(log *obj.Log) *Op
  • func (op *Op) CommitWait(wait bool) bool
  • func (op *Op) NDirty() uint64
  • func (op *Op) OverWrite(addr addr.Addr, sz uint64, data []byte)
  • func (op *Op) ReadBuf(addr addr.Addr, sz uint64) *buf.Buf

Constants

const LogBlocks uint64 = 511

LogBlocks is the maximum number of blocks that can be written in one operation

const LogBytes uint64 = 4096 * 511

LogBytes is the maximum size of an operation, in bytes

Types

type Op

type Op struct {
	// contains filtered or unexported fields
}

Op is an in-progress journal operation.

Call CommitWait to persist the operation's writes. To abort the operation simply stop using it.

func Begin

func Begin(log *obj.Log) *Op

Begin starts a local journal operation with no writes from a global object manager.

func (*Op) CommitWait

func (op *Op) CommitWait(wait bool) bool

CommitWait commits the writes in the transaction to disk.

If CommitWait returns false, the transaction failed and had no logical effect. This can happen, for example, if the transaction is too big to fit in the on-disk journal.

wait=true is a synchronous commit, which is durable as soon as CommitWait returns.

wait=false is an asynchronous commit, which can be made durable later with Flush.

func (*Op) NDirty

func (op *Op) NDirty() uint64

NDirty reports an upper bound on the size of this transaction when committed.

The caller cannot rely on any particular properties of this function for safety.

func (*Op) OverWrite

func (op *Op) OverWrite(addr addr.Addr, sz uint64, data []byte)

OverWrite writes an object to addr

func (*Op) ReadBuf

func (op *Op) ReadBuf(addr addr.Addr, sz uint64) *buf.Buf