gbr_disk_log - v1.1.0

gbr/disk_log

GBR Disk Log: A Type-Safe wrapper for Erlang’s disk_log.

This module provides an idiomatic Gleam interface for creating and managing disk logs. It supports various log types (halt, wrap, rotate), formats (internal, external), and logging modes.

The disk_log module is part of Erlang’s kernel application and is widely used for building reliable, disk-backed logging systems that prevent Out-Of-Memory (OOM) errors in high-throughput environments.

When to use it?

It is ideal for telemetry, audit logs, and actor state persistence where you need a bounded disk footprint (ring buffers) without blocking actor mailboxes or causing OOM.

Types

ChunkData

</>

Data returned from a chunked read operation.

pub type ChunkData {
  Eof
  Chunk(continuation: Continuation, terms: List(BitArray))
}

Constructors 

  • Eof

    End of file reached.

  • Chunk(continuation: Continuation, terms: List(BitArray))

    A chunk of data with its continuation.

Continuation

</>

A continuation for chunked reading of log data.

pub type Continuation {
  Continuation(dynamic.Dynamic)
}

Constructors

DiskLogError

</>

Possible errors returned by disk log operations.

pub type DiskLogError {
  DiskLogError(reason: String)
}

Constructors 

  • DiskLogError(reason: String)

LogDisk

opaque </>

A handle to a disk log.

pub opaque type LogDisk

LogFormat

</>

The format of the log data.

pub type LogFormat {
  Internal
  External
}

Constructors 

  • Internal

    Internal Erlang term format.

  • External

    External binary format.

LogInfo

</>

Detailed information about a disk log.

pub type LogInfo {
  LogInfo(
    name: String,
    file: String,
    type_: LogType,
    format: LogFormat,
    size: LogSize,
    mode: LogMode,
  )
}

Constructors

LogMode

</>

The access mode for the log.

pub type LogMode {
  ReadOnly
  ReadWrite
}

Constructors 

  • ReadOnly

    Open the log in read-only mode.

  • ReadWrite

    Open the log in read-write mode.

LogOptions

opaque </>

Configuration options for opening a disk log.

pub opaque type LogOptions

LogRepair

</>

The strategy for repairing a log if it’s found to be corrupted.

pub type LogRepair {
  Enable
  Truncate
  Disabled
}

Constructors 

  • Enable

    Enable repair if needed.

  • Truncate

    Truncate the log if corrupted.

  • Disabled

    Disable repair.

LogSize

</>

The maximum size of the log.

pub type LogSize {
  Infinity
  MaxBytes(Int)
  WrapSize(max_bytes: Int, max_files: Int)
}

Constructors 

  • Infinity

    No size limit.

  • MaxBytes(Int)

    Maximum bytes for a single file.

  • WrapSize(max_bytes: Int, max_files: Int)

    Maximum bytes and number of files for a wrap log.

LogType

</>

The type of log to create.

pub type LogType {
  Halt
  Wrap
  Rotate
}

Constructors 

  • Halt

    A single file log.

  • Wrap

    A sequence of wrap files.

  • Rotate

    A sequence of rotate files (only external format).

Values

async_log

</> 
pub fn async_log(
  log: LogDisk,
  data: BitArray,
) -> Result(LogDisk, DiskLogError)

Log data to a disk log asynchronously.

This function returns immediately after sending the data to the log process.

binary_async_log

</> 
pub fn binary_async_log(
  log: LogDisk,
  data: BitArray,
) -> Result(LogDisk, DiskLogError)

Log binary data to a disk log asynchronously.

Similar to async_log, but optimized for binary data.

block

</> 
pub fn block(
  log: LogDisk,
  queue: Bool,
) -> Result(LogDisk, DiskLogError)

Block a log for maintenance.

When blocked, no new entries can be logged until unblock is called. If queue is true, logging requests are queued.

chunk

</> 
pub fn chunk(
  log: LogDisk,
  cont: Continuation,
) -> Result(ChunkData, DiskLogError)

Read a chunk of data from the log starting at the given continuation.

Use start_continuation() to begin reading from the start of the log.

close

</> 
pub fn close(log: LogDisk) -> Result(LogDisk, DiskLogError)

Close a disk log.

file

</> 
pub fn file(options: LogOptions, path: String) -> LogOptions

Set the file path for the log.

format

</> 
pub fn format(options: LogOptions, f: LogFormat) -> LogOptions

Set the log format.

increment_wrap_file

</> 
pub fn increment_wrap_file(
  log: LogDisk,
) -> Result(LogDisk, DiskLogError)

Force a wrap log to move to the next file in the sequence.

info

</> 
pub fn info(log: LogDisk) -> Result(LogInfo, DiskLogError)

Get detailed information about the log state.

log

</> 
pub fn log(
  log: LogDisk,
  data: BitArray,
) -> Result(LogDisk, DiskLogError)

Log data to a disk log synchronously.

This function waits until the data is written to disk (or the OS buffers).

new

</> 
pub fn new(name: String) -> LogDisk

Create a new LogDisk instance from a name.

let log = disk_log.new("my_log")

open

</> 
pub fn open(log: LogDisk) -> Result(LogDisk, DiskLogError)

Open a disk log with default options.

If the log is already open, it returns the existing handle.

open_options

</> 
pub fn open_options(
  log: LogDisk,
  options: LogOptions,
) -> Result(LogDisk, DiskLogError)

Open a disk log with specific options.

options_empty

</> 
pub const options_empty: LogOptions

Empty configuration options.

repair

</> 
pub fn repair(options: LogOptions, r: LogRepair) -> LogOptions

Set the repair strategy.

size

</> 
pub fn size(options: LogOptions, s: LogSize) -> LogOptions

Set the log size.

start_continuation

</> 
pub fn start_continuation() -> Continuation

Get the initial continuation for reading from the beginning of the log.

sync

</> 
pub fn sync(log: LogDisk) -> Result(LogDisk, DiskLogError)

Synchronize the log buffers to disk.

type_

</> 
pub fn type_(options: LogOptions, t: LogType) -> LogOptions

Set the log type.

unblock

</> 
pub fn unblock(log: LogDisk) -> Result(LogDisk, DiskLogError)

Unblock a previously blocked log.

✨ Search Document