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.

Types

ChunkData

</>

Data returned from a chunked read operation.

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

Constructors

```
Eof
```
End of file reached.

Chunk(continuation: core.Continuation, terms: List(BitArray))

A chunk of data with its continuation.

Continuation

</>

A continuation for chunked reading of log data.

pub type Continuation =
  core.Continuation

DiskLogError

</>

Possible errors returned by disk log operations.

pub type DiskLogError =
  core.DiskLogError

LogDisk

</>

A handle to a disk log.

pub type LogDisk =
  core.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 =
  core.LogInfo

LogMode

</>

The access mode for the log.

pub type LogMode =
  core.LogMode

LogOpts

</>

Configuration options for opening a disk log.

pub type LogOpts =
  core.LogOpts

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

alog

</>

pub fn alog(
  log: core.LogDisk,
  data: BitArray,
) -> Result(core.LogDisk, core.DiskLogError)

Log data to a disk log asynchronously.

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

balog

</>

pub fn balog(
  log: core.LogDisk,
  data: BitArray,
) -> Result(core.LogDisk, core.DiskLogError)

Log binary data to a disk log asynchronously.

Similar to alog, but optimized for binary data.

block

</>

pub fn block(
  log: core.LogDisk,
  queue: Bool,
) -> Result(core.LogDisk, core.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: core.LogDisk,
  cont: core.Continuation,
) -> Result(ChunkData, core.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: core.LogDisk,
) -> Result(core.LogDisk, core.DiskLogError)

Close a disk log.

file

</>

pub fn file(opts: core.LogOpts, path: String) -> core.LogOpts

Set the file path for the log.

format

</>

pub fn format(opts: core.LogOpts, f: LogFormat) -> core.LogOpts

Set the log format.

inc_wrap_file

</>

pub fn inc_wrap_file(
  log: core.LogDisk,
) -> Result(core.LogDisk, core.DiskLogError)

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

info

</>

pub fn info(
  log: core.LogDisk,
) -> Result(core.LogInfo, core.DiskLogError)

Get detailed information about the log state.

log

</>

pub fn log(
  log: core.LogDisk,
  data: BitArray,
) -> Result(core.LogDisk, core.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) -> core.LogDisk

Create a new LogDisk instance from a name.

let log = disk_log.new("my_log")

open

</>

pub fn open(
  log: core.LogDisk,
) -> Result(core.LogDisk, core.DiskLogError)

Open a disk log with default options.

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

open_opts

</>

pub fn open_opts(
  log: core.LogDisk,
  opts: core.LogOpts,
) -> Result(core.LogDisk, core.DiskLogError)

Open a disk log with specific options.

opts_empty

</>

pub const opts_empty: core.LogOpts

Empty configuration options.

repair

</>

pub fn repair(opts: core.LogOpts, r: LogRepair) -> core.LogOpts

Set the repair strategy.

size

</>

pub fn size(opts: core.LogOpts, s: LogSize) -> core.LogOpts

Set the log size.

start_continuation

</>

pub fn start_continuation() -> core.Continuation

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

sync

</>

pub fn sync(
  log: core.LogDisk,
) -> Result(core.LogDisk, core.DiskLogError)

Synchronize the log buffers to disk.

type_

</>

pub fn type_(opts: core.LogOpts, t: LogType) -> core.LogOpts

Set the log type.

unblock

</>

pub fn unblock(
  log: core.LogDisk,
) -> Result(core.LogDisk, core.DiskLogError)

Unblock a previously blocked log.