Malachi.Log.Segment (malachi v0.8.13)

View Source

Metadata describing one segment: the unit of replication in NorthGuard's model.

A segment is a sequence of Malachi.Log.Records persisted to a single file (file-per-segment). It is either :active (records may be appended) or :sealed (immutable). A segment is sealed when it reaches a size limit, exceeds a maximum active age, or (in a replicated deployment) on replica failure.

This struct is pure data; durable I/O lives in Malachi.Storage.SegmentStore implementations. The counters here (byte_size, record_count) reflect flushed (durable, committed) state, not data still buffered in memory.

Summary

Types

id()
state()
t()

Functions

end_offset(segment)

The logical offset after the last committed record (exclusive end).

index_path(segment)

Absolute path of the segment's persisted sparse index sidecar.

new(id, directory, opts \\ [])

Builds active segment metadata.

path(segment)

Absolute path of the segment's data file.

seal_marker_path(segment)

Absolute path of the segment's seal marker.

sealed?(segment)

Whether the segment is sealed (immutable).

should_seal?(segment, now_ms)

Whether an active segment has hit a seal threshold (size or age) at time now_ms. Always false for an already-sealed segment.

Types

id()

@type id() :: term()

state()

@type state() :: :active | :sealed

t()

@type t() :: %Malachi.Log.Segment{
  base_offset: non_neg_integer(),
  byte_size: non_neg_integer(),
  created_at: non_neg_integer(),
  directory: Path.t(),
  id: id(),
  max_age_ms: pos_integer(),
  max_bytes: pos_integer(),
  record_count: non_neg_integer(),
  sealed_at: non_neg_integer() | nil,
  state: state()
}

Functions

end_offset(segment)

@spec end_offset(t()) :: non_neg_integer()

The logical offset after the last committed record (exclusive end).

index_path(segment)

@spec index_path(t()) :: Path.t()

Absolute path of the segment's persisted sparse index sidecar.

new(id, directory, opts \\ [])

@spec new(id(), Path.t(), keyword()) :: t()

Builds active segment metadata.

Options

  • :base_offset - logical offset of this segment's first record (default 0)
  • :max_bytes - seal threshold in bytes (default 1GB)
  • :max_age_ms - seal threshold for active age (default 1h)
  • :created_at - epoch ms (default: now)

path(segment)

@spec path(t()) :: Path.t()

Absolute path of the segment's data file.

seal_marker_path(segment)

@spec seal_marker_path(t()) :: Path.t()

Absolute path of the segment's seal marker.

sealed?(segment)

@spec sealed?(t()) :: boolean()

Whether the segment is sealed (immutable).

should_seal?(segment, now_ms)

@spec should_seal?(t(), non_neg_integer()) :: boolean()

Whether an active segment has hit a seal threshold (size or age) at time now_ms. Always false for an already-sealed segment.