0.5.1

core/gay.zharel.fateweaver.log/FateLogWriter

FateLogWriter

class FateLogWriter @JvmOverloads constructor(val sink: FateSink, val timeSource: TimeSource = TimeSource.Monotonic) : AutoCloseable

Writes a FateWeaver log to a FateSink. A log holds any number of typed channels.

Each channel has a type, so the compiler rejects a value that doesn't match its schema. Schemas are written into the log, so a reader can decode the file without the classes that produced it. Most types need no hand-written schema, because createChannel infers one from a class.

File format

The file starts with a 4-byte header of magic bytes and a version. After that comes a run of entries. A schema entry (kind 0) defines a channel. A message entry (kind 1) carries one value for a channel that is already defined. Since version 3, every message entry also carries the time it was logged, in nanoseconds, so readers can line up channels without a timestamp channel.

Timestamps

write without a timestamp stamps the entry with the time elapsed on timeSource since this writer was created. Only differences between stamps mean anything. A writer fed by a gay.zharel.fateweaver.telemetry.FateLogBackend gets its stamps from the registry instead.

Threading

A writer can be shared between threads. The sink receives entries one at a time, and a channel's schema entry always comes before its first message.

Example

FateLogWriter.create("mylog.fate").use { writer ->
    val userChannel = writer.createChannel("users", User::class)
    val eventChannel = writer.createChannel("events", Event::class)

    userChannel.put(User("alice", 25))
    eventChannel.put(Event("login", System.currentTimeMillis()))
}

Parameters

sink

Where the log bytes go

timeSource

Stamps entries written without a timestamp. Defaults to TimeSource.Monotonic.

Constructors

constructor(stream: OutputStream, timeSource: TimeSource = TimeSource.Monotonic)

Creates a writer that writes to stream, as in file logging.

constructor(sink: FateSink, timeSource: TimeSource = TimeSource.Monotonic)

Types

object Companion

inner class WriterChannel<T> : LogChannel<T>

A LogChannel bound to one FateLogWriter. Writes to it go to that writer.

Properties

val sink: FateSink

val timeSource: TimeSource

Functions

fun <T> addChannel(channel: FateLogWriter.WriterChannel<T>): FateLogWriter.WriterChannel<T>

Registers channel and writes its schema entry to the sink right away.

fun <T> addChannel(channel: LogChannel<T>): FateLogWriter.WriterChannel<T>

Returns this writer's channel with the same name as channel.

open override fun close()

Flushes and closes the sink. Don't write after this.

operator fun contains(channel: LogChannel<*>): <Error class: unknown class>

Returns whether this writer has a channel with the same name as channel.

inline fun <T : Any> createChannel(name: String): FateLogWriter.WriterChannel<T>

Creates a channel whose schema is inferred from the reified type T, type arguments included. Prefer this to the KClass overload, which loses them.

fun <T> createChannel(name: String, schema: FateSchema<T>): FateLogWriter.WriterChannel<T>

Creates a channel with the given name and schema, and adds it to the log.

fun <T : Any> createChannel(name: String, cls: Class<T>): FateLogWriter.WriterChannel<T>

fun <T : Any> createChannel(name: String, cls: KClass<T>): <Error class: unknown class>

Creates a channel with the given name and a schema inferred from cls by reflection.

fun timestamp(): Long

Nanoseconds elapsed on timeSource since this writer was created.

open override fun toString(): String

fun <T> write(channel: LogChannel<T>, obj: T)

Writes an object to the specified channel, stamped with the current timestamp.

fun <T> write(channel: LogChannel<T>, obj: T, timestamp: Long)

Writes an object to the specified channel, stamped with timestamp.

fun write(channelName: String, obj: Any, type: KType)

Writes an object to a channel identified by name, inferring the schema from type instead of from obj's erased runtime class.

inline fun <T : Any> FateLogWriter.write(channelName: String, obj: T)

Writes an object to a channel identified by name, inferring the schema from T, type arguments included.

@JvmName(name = "write")

fun writeErased(channelName: String, obj: Any)

Writes an object to a channel identified by name, inferring the schema from the object's runtime class.