docs
0.5.0-SNAPSHOT
API
Generated with
Copyright (c) 2022, Yan Kun/Otavia Project
Copyright (c) 2022, Yan Kun/Otavia Project
docs/cc.otavia/cc.otavia.core/cc.otavia.core.config

cc.otavia.core.config

package cc.otavia.core.config

Members list

Type members

Classlikes

case class ActorSystemConfig(actorThreadPoolSize: Int = ..., memoryMonitor: Boolean = ..., memoryMonitorDurationMs: Int = ..., memoryOverSleepMs: Int = ..., systemMonitor: Boolean = ..., systemMonitorDurationMs: Int = ..., printBanner: Boolean = ..., aggressiveGC: Boolean = ..., maxBatchSize: Int = ..., maxFetchPerRunning: Int = ..., poolHolderMaxSize: Int = ...)

System-level configuration for cc.otavia.core.system.ActorSystem.

System-level configuration for cc.otavia.core.system.ActorSystem.

Value parameters

actorThreadPoolSize

Number of ActorThread worker threads. Defaults to available processors.

aggressiveGC

Enable aggressive garbage collection behavior. When true, the system proactively triggers GC when memory pressure is detected.

maxBatchSize

Maximum number of messages processed in a single actor dispatch cycle. Prevents any single actor from monopolizing the thread indefinitely.

maxFetchPerRunning

Maximum number of messages fetched per actor run. Controls how many messages are dequeued before yielding.

memoryMonitor

Enable heap memory pressure monitoring. When enabled, the system tracks heap usage and marks itself as "busy" when memory is over 90% utilized.

memoryMonitorDurationMs

Interval in milliseconds between memory monitor checks. Default is 2000ms.

memoryOverSleepMs

Sleep time in milliseconds when system is busy and a non-actor thread sends a notice. Prevents non-actor threads from overwhelming the system during memory pressure.

poolHolderMaxSize

Maximum number of pooled objects per cc.otavia.core.cache.SingleThreadPoolableHolder. Controls memory vs allocation overhead tradeoff for object pools.

printBanner

Print the Otavia ASCII banner on system startup.

systemMonitor

Enable system-wide metrics monitoring task. Collects runtime statistics for debugging/observability.

systemMonitorDurationMs

Interval in milliseconds between system monitor runs. Default is 1000ms.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class ActorSystemConfigBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
case class BufferConfig(pageSize: Int = ..., minCache: Int = ..., maxCache: Int = ...)

Buffer allocation configuration.

Buffer allocation configuration.

Value parameters

maxCache

Maximum number of pages cached per-thread allocator. Limits memory consumption from buffer caching. Must be greater than or equal to minCache. Default is 10240.

minCache

Minimum number of pages cached per-thread allocator. Ensures a baseline of cached pages to avoid allocation thrashing. Must be at least 1. Default is 8.

pageSize

Page size in bytes for buffer allocation. Must be a power of 2 and one of {1024, 2048, 4096, 8192, 16384}. Default is 4096 (4KB). Larger pages reduce allocation overhead but increase memory consumption for small buffers.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class BufferConfigBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
case class ChannelConfig(connectTimeoutMs: Int = ..., writeWaterMarkLow: Int = ..., writeWaterMarkHigh: Int = ..., maxFutureInflight: Int = ..., maxStackInflight: Int = ..., maxMessagesPerRead: Int = ...)

Channel configuration defaults.

Channel configuration defaults.

Value parameters

connectTimeoutMs

Default TCP connect timeout in milliseconds. Applied when no explicit timeout is set on the connect operation. Default is 30000ms (30 seconds).

maxFutureInflight

Maximum number of pipelined requests (ChannelFutures) that can be in-flight without waiting for responses. Enables high-performance pipelined protocols like Redis pipeline and HTTP/2 multiplexing. Default is 1.

maxMessagesPerRead

Maximum number of messages to read per read loop iteration for server channels. Controls read batching. Default is 16.

maxStackInflight

Maximum number of inbound server requests (ChannelStacks) that can be processed concurrently per channel. Default is 1.

writeWaterMarkHigh

High watermark for write buffer in bytes. When the write buffer size exceeds this threshold, the channel becomes non-writable, triggering backpressure. Default is 65536 (64KB).

writeWaterMarkLow

Low watermark for write buffer in bytes. When the write buffer size drops below this threshold after being above the high watermark, the channel becomes writable again. Default is 32768 (32KB).

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class ChannelConfigBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
trait ModuleConfig

SPI trait for module-specific configuration.

SPI trait for module-specific configuration.

Modules (handler, codec-, sql-, etc.) can define their own configuration by implementing this trait and registering the config instance with OtaviaConfigBuilder.withModuleConfig. The config system stores module configs by Class key for type-safe retrieval.

Example:

// In handler module:
case class SslConfig(cacheBufferSize: Int = 20480) extends ModuleConfig:
  override def propertyPrefix: String = "cc.otavia.handler.ssl"

// Registration:
val config = OtaviaConfigBuilder()
  .withModuleConfig(SslConfig(cacheBufferSize = 32768))
  .build()

// Retrieval:
val sslCfg = system.config.getModuleConfig(classOf[SslConfig])

Attributes

Supertypes
class Object
trait Matchable
class Any
Known subtypes
class SslConfig
case class OtaviaConfig(name: String = ..., system: ActorSystemConfig = ..., buffer: BufferConfig = ..., scheduler: SchedulerConfig = ..., reactor: ReactorConfig = ..., channel: ChannelConfig = ..., timer: TimerConfig = ..., spinLock: SpinLockConfig = ..., priority: PriorityConfig = ..., moduleConfigs: Map[Class[_], ModuleConfig] = ...)

Immutable top-level configuration for an cc.otavia.core.system.ActorSystem.

Immutable top-level configuration for an cc.otavia.core.system.ActorSystem.

Built once via OtaviaConfigBuilder and passed to the actor system at creation time. All config groups are immutable case classes with sensible defaults.

Configuration values follow a priority chain: explicit builder value > system property (-D) > hardcoded default.

Example usage:

val system = ActorSystem("my-app") { builder =>
  builder.actorThreadPoolSize(4)
    .pageSize(8)
    .ioRatio(60)
    .withModuleConfig(SslConfig(cacheBufferSize = 32768))
}

// Access config from anywhere
system.config.buffer.pageSize
system.config.scheduler.ioRatio

Value parameters

buffer

Buffer allocation configuration: page size, allocator cache sizes.

channel

Channel defaults: connect timeout, write watermarks, inflight limits.

name

Name of the actor system. Used for logging and identification. Default is "ActorSystem: ".

priority

Scheduling priority thresholds: mailbox sizes that trigger high priority.

reactor

NIO reactor configuration: worker count, selector tuning.

scheduler

Actor scheduling configuration: IO ratio, time budgets, work stealing thresholds.

spinLock

Spin lock tuning: spin/yield/park thresholds.

system

System-level configuration: thread pool sizing, memory/system monitors, GC behavior.

timer

Hashed wheel timer configuration: tick duration, wheel size.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object OtaviaConfig

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
class OtaviaConfigBuilder

Builder for constructing OtaviaConfig instances.

Builder for constructing OtaviaConfig instances.

Provides a fluent API for configuring the actor system. All setter methods return this for chaining.

Configuration values follow a priority chain: explicit builder value > system property (-D) > hardcoded default.

Example:

val config = OtaviaConfigBuilder()
  .name("my-system")
  .actorThreadPoolSize(4)
  .pageSize(8)
  .ioRatio(60)
  .withModuleConfig(SslConfig(cacheBufferSize = 32768))
  .build()

val system = ActorSystem(config)

For convenience, you can also use the callback style:

val system = ActorSystem("my-system") { builder =>
  builder.actorThreadPoolSize(4).ioRatio(60)
}

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
object OtaviaConfigBuilder

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
case class PriorityConfig(highPriorityReplySize: Int = ..., highPriorityEventSize: Int = ...)

Actor scheduling priority configuration.

Actor scheduling priority configuration.

The actor scheduler uses a three-signal model to determine whether an actor should be scheduled with high priority. High-priority actors are dispatched before normal-priority actors, reducing latency for actors that need prompt attention.

Value parameters

highPriorityEventSize

Event mailbox size threshold to boost scheduling priority. When an actor's event mailbox contains more than this many messages, the actor is scheduled with high priority. System events (timer expirations, channel lifecycle) need timely processing to maintain system responsiveness. Default is 4.

highPriorityReplySize

Reply mailbox size threshold to boost scheduling priority. When an actor's reply mailbox contains more than this many messages, the actor is scheduled with high priority. Each reply corresponds to a completable cc.otavia.core.channel.MessagePromise — processing it completes a future and may unblock suspended stacks. Default is 2.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class PriorityConfigBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
case class ReactorConfig(maxTasksPerRun: Int = ..., nioWorkerSize: Int = ..., selectorAutoRebuildThreshold: Int = ..., noKeySetOptimization: Boolean = ...)

NIO reactor configuration.

NIO reactor configuration.

Value parameters

maxTasksPerRun

Maximum number of IO tasks processed per reactor loop iteration. Controls responsiveness vs throughput tradeoff. Default is 16.

nioWorkerSize

Number of NIO reactor worker threads. Defaults to available processors. These threads handle selector polling and channel IO events.

noKeySetOptimization

Disable the SelectedSelectionKeySet optimization that replaces the selector's internal key set with a more efficient implementation. May be needed on certain JVMs or for debugging. Default is false.

selectorAutoRebuildThreshold

Number of consecutive premature Selector returns before rebuilding the Selector to work around the epoll 100% CPU bug. Set to 0 to disable auto-rebuild. Default is 512.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class ReactorConfigBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
case class SchedulerConfig(ioRatio: Int = ..., minBudgetMicros: Int = ..., stealFloor: Int = ..., stealAggression: Int = ...)

Actor scheduling configuration for the event loop.

Actor scheduling configuration for the event loop.

Value parameters

ioRatio

Percentage of event loop time allocated to IO (0-100). The remaining time is allocated to StateActor execution. Default is 50 (equal time for IO and actors). Set to 100 to disable time budgeting for actors.

minBudgetMicros

Minimum time budget in microseconds for StateActor execution when there are no IO events. Prevents actor starvation when the system is idle from an IO perspective. Default is 500μs.

stealAggression

Product threshold for the adaptive steal condition: idleCount × readies >= stealAggression. Higher values make stealing more conservative (require more idle iterations or deeper backlog). Default is 128.

stealFloor

Minimum victim queue depth to consider work stealing. Below this threshold the owner thread will self-drain quickly, and the CPU cache cost of cross-thread execution outweighs the benefit. Default is 32.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class SchedulerConfigBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
case class SpinLockConfig(spinThreshold: Int = ..., yieldThreshold: Int = ..., parkNanos: Long = ...)

Spin lock tuning configuration.

Spin lock tuning configuration.

Spin locks use adaptive spinning with progressive backoff through three phases:

  1. Pure spin with Thread.onSpinWait (x86 PAUSE instruction)
  2. Thread.yield to hint the OS scheduler
  3. LockSupport.parkNanos to truly free the CPU core

The critical sections protected by spin locks are typically only a few instructions (pointer assignment + counter update), so uncontended or lightly contended CAS usually succeeds within 1-2 attempts.

Value parameters

parkNanos

Duration in nanoseconds to park in Phase 3. Triggered during long GC STW pauses (10-200ms) where the lock holder is suspended at a safepoint. Default is 1000ns (1μs).

spinThreshold

Number of spin iterations in Phase 1 before switching to yield. Covers the common case of uncontended or lightly contended lock acquisition. Default is 100.

yieldThreshold

Number of spin iterations before switching from yield to park. Entered when the lock holder has been preempted by the OS scheduler or paused by a brief GC event. Default is 200.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class SpinLockConfigBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
case class TimerConfig(tickDurationMs: Long = ..., ticksPerWheel: Int = ...)

Hashed wheel timer configuration.

Hashed wheel timer configuration.

The timer uses a hashed wheel data structure for efficient timeout scheduling with O(1) add/cancel operations. Based on George Varghese and Tony Lauck's paper "Hashed and Hierarchical Timing Wheels".

Value parameters

tickDurationMs

Duration in milliseconds between timer ticks. The timer checks for expired timeouts on each tick. Smaller values provide better accuracy but increase CPU overhead. In most network applications, I/O timeouts do not need to be precise. Default is 100ms.

ticksPerWheel

Number of slots in the timing wheel (wheel size). Larger wheels can schedule more timeouts with less hash collisions but consume more memory. Must be a power of 2. Default is 512.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class TimerConfigBuilder

Attributes

Supertypes
class Object
trait Matchable
class Any
Generated with
Copyright (c) 2022, Yan Kun/Otavia Project
Copyright (c) 2022, Yan Kun/Otavia Project