journal

Documentation

Overview

Package journal is the append-only event log of everything the colony does: the durable spine under the D2 event stream and the source for replay (doc 01 section 8). The log leads and the stream follows: an event reaches subscribers only after the writer has sequenced and written it, so any "I saw up to N" is a valid resume cursor.

Index

• Constants
• type Journal
  • func Open(dir string, sink Sink) (*Journal, error)
  • func (j *Journal) Append(e event.Event) event.Event
  • func (j *Journal) Close() error
  • func (j *Journal) Cursor() uint64
  • func (j *Journal) Since(ctx context.Context, after uint64) ([]event.Event, error)
  • func (j *Journal) Start(ctx context.Context) error
• type Sink

Constants

const DefaultRotateBytes = 8 << 20

DefaultRotateBytes is the size a journal file grows to before the writer rolls to the next index (doc 01 section 8.3).

Types

type Journal

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

Journal is the append-only event log. Append stamps Seq and Time under a lock and enqueues; one writer goroutine drains the queue in order, writes each line, then hands the event to the sink.

func Open

func Open(dir string, sink Sink) (*Journal, error)

Open prepares a journal in dir, scanning existing files so Seq continues gap-free across restarts. No goroutine starts until Start.

func (*Journal) Append

func (j *Journal) Append(e event.Event) event.Event

Append stamps Seq and Time and enqueues the event for durable logging. It returns the stamped event after it is queued, not after it is on disk; ordering is the single writer's, durability its flush policy. Between Close and the process end the stamp still happens but nothing is logged or fanned out; the colony stops producing before it closes.

func (*Journal) Close

func (j *Journal) Close() error

Close stops the writer, flushes, and closes the file. Idempotent.

func (*Journal) Cursor

func (j *Journal) Cursor() uint64

Cursor is the last Seq assigned, the resume point a fresh subscriber's hello carries.

func (*Journal) Since

func (j *Journal) Since(ctx context.Context, after uint64) ([]event.Event, error)

Since returns events with Seq greater than after, for replay and for a resuming client. It reads the log files, never the queue or the bus.

func (*Journal) Start

func (j *Journal) Start(ctx context.Context) error

Start brings the writer goroutine up. Separate from Open so the colony controls goroutine lifetimes (doc 01 section 4.1).

type Sink

type Sink func(event.Event)

Sink receives each event after it is durably written, in Seq order. The colony points this at the bus; the journal stays upstream of any lossy fan-out (doc 01 section 8.2).