🥮 mooncakes.io
README

#core — 仿真内核层

MoonDES 层级1：提供仿真环境、事件队列、主仿真循环。

#API 概览

符号说明
SimulationEnv全局仿真环境
EventQueue最小堆优先级事件队列
Event仿真事件
EnvSnapshot环境状态快照
new_env(until=)创建仿真环境
new_queue()创建空事件队列
new_event(id=, time=, callback=)创建事件
SimulationEnv::run()主仿真循环
SimulationEnv::step()单步推进
SimulationEnv::schedule(time=, callback=)调度事件
SimulationEnv::event_count()已注册事件数
SimulationEnv::snapshot()捕获状态快照
SimulationEnv::restore(snap)从快照恢复

#示例

///|
test {
  let env = new_env(until=10.0)
  inspect(env.now(), content="0")
  let log : Array[String] = []
  ignore(env.schedule(time=3.0, callback=fn() { log.push("A") }))
  ignore(env.schedule(time=1.0, callback=fn() { log.push("B") }))
  env.run()
  assert_eq(log[0], "B")
  assert_eq(log[1], "A")
  inspect(env.event_count(), content="2")
}

///|
test {
  let q = new_queue()
  inspect(q.is_empty(), content="true")
  let e = new_event(id=0, time=1.0, callback=fn() { () })
  q.push(e)
  inspect(q.length(), content="1")
}

#
EventId

source
type EventId = Int

事件 ID 类型，用于唯一标识事件

#
EventPriority

source
type EventPriority = Int

事件优先级：数值越小优先级越高

#
ProcessId

source
type ProcessId = Int

仿真进程 ID 类型

#
EnvSnapshot

source
pub(all) struct EnvSnapshot {
  now : Double
  status : EnvStatus
  next_event_id : Int
  next_process_id : Int
} derive(Eq, ToJson, 
Debug)

环境状态快照（用于断点回滚）

捕获仿真环境的可变状态，可通过 restore 恢复。 注意：仅恢复时钟、状态、ID 计数器，不恢复事件队列与回调。

#
EnvStatus

source
pub(all) enum EnvStatus {
  Initialized
  Running
  Finished
} derive(Eq, ToJson, 
Debug)

仿真环境状态

#
Event

source
pub(all) struct Event {
  id : Int
  time : Double
  priority : Int
  status : EventStatus
  callbacks : Array[() -> Unit]
}

仿真事件

事件是离散事件仿真的基本调度单元，按 (time, priority) 排序： 时间越小越早执行，同一时间下优先级数值越小越先执行。

#
Event::add_callback

source
fn Event::add_callback(self : Event, callback : () -> Unit) -> Unit

向事件追加回调

#
Event::cancel

source
fn Event::cancel(self : Event) -> Unit

取消事件

#
Event::is_pending

source
fn Event::is_pending(self : Event) -> Bool

事件是否仍待处理

#
Event::trigger

source
fn Event::trigger(self : Event) -> Unit

触发事件：执行所有回调

#
EventQueue

source
pub(all) struct EventQueue {
  heap : Array[Event]
}

最小堆优先级事件队列

按 (time, priority) 维护最小堆，保证每次弹出的是时间最早、优先级最高的事件。 这是离散事件仿真时序正确性的核心保证。

#
EventQueue::is_empty

source
fn EventQueue::is_empty(self : EventQueue) -> Bool

队列是否为空

#
EventQueue::length

source
fn EventQueue::length(self : EventQueue) -> Int

队列中事件数量

#
EventQueue::peek

source
fn EventQueue::peek(self : EventQueue) -> Event?

查看堆顶事件（不弹出），返回 None 如果队列为空

#
EventQueue::pop

source
fn EventQueue::pop(self : EventQueue) -> Event?

弹出堆顶事件（下沉调整），返回 None 如果队列为空

#
EventQueue::push

source
fn EventQueue::push(self : EventQueue, event : Event) -> Unit

插入事件到队列（上浮调整）

#
EventQueue::remove_canceled

source
fn EventQueue::remove_canceled(self : EventQueue) -> Unit

移除所有已取消的事件（惰性清理）

#
EventStatus

source
pub(all) enum EventStatus {
  Pending
  Triggered
  Canceled
} derive(Eq, 
Debug)

事件状态

#
SimulationEnv

source
pub(all) struct SimulationEnv {
  now : Double
  until : Double
  queue : EventQueue
  status : EnvStatus
  next_event_id : Int
  next_process_id : Int
  events : Map[Int, Event]
  on_step_hook : (SimulationEnv, Double) -> Unit?
  on_event_hook : (SimulationEnv, Event) -> Unit?
  on_finish_hook : (SimulationEnv) -> Unit?
}

全局仿真环境

管理虚拟仿真时钟、事件队列和主仿真循环。 内核完全无全局可变共享状态，天然支持多实例并行仿真。 支持插件钩子：on_step / on_event / on_finish，由 plugin::attach 设置。

#
SimulationEnv::_alloc_event_id

source
fn SimulationEnv::_alloc_event_id(self : SimulationEnv) -> Int

分配新的事件 ID

#
SimulationEnv::_alloc_process_id

source
fn SimulationEnv::_alloc_process_id(self : SimulationEnv) -> Int

分配新的进程 ID

#
SimulationEnv::_register_event

source
fn SimulationEnv::_register_event(self : SimulationEnv, event : Event) -> Unit

注册事件到环境（供外部创建的 Event 加入队列）

#
SimulationEnv::_set_on_event_hook

source
fn SimulationEnv::_set_on_event_hook(self : SimulationEnv, hook : (SimulationEnv, Event) -> Unit?) -> Unit

设置 on_event 钩子（事件触发后调用）

#
SimulationEnv::_set_on_finish_hook

source
fn SimulationEnv::_set_on_finish_hook(self : SimulationEnv, hook : (SimulationEnv) -> Unit?) -> Unit

设置 on_finish 钩子（仿真结束时调用）

#
SimulationEnv::_set_on_step_hook

source
fn SimulationEnv::_set_on_step_hook(self : SimulationEnv, hook : (SimulationEnv, Double) -> Unit?) -> Unit

设置 on_step 钩子（每个事件处理前调用）

#
SimulationEnv::event_count

source
fn SimulationEnv::event_count(self : SimulationEnv) -> Int

获取已注册的事件总数

#
SimulationEnv::get_event

source
fn SimulationEnv::get_event(self : SimulationEnv, id : Int) -> Event?

按事件 ID 查找事件

#
SimulationEnv::is_finished

source
fn SimulationEnv::is_finished(self : SimulationEnv) -> Bool

仿真是否已结束

#
SimulationEnv::now

source
fn SimulationEnv::now(self : SimulationEnv) -> Double

获取当前仿真时间

#
SimulationEnv::restore

source
fn SimulationEnv::restore(self : SimulationEnv, snap : EnvSnapshot) -> Unit

从快照恢复环境状态

恢复时钟、状态、ID 计数器。事件队列与回调不恢复。

#
SimulationEnv::run

source
fn SimulationEnv::run(self : SimulationEnv) -> Unit

主仿真循环：按时间顺序处理所有事件直到队列为空或到达终止时间

Example

test {
  let env = @core.new_env(until=10.0)
  let log : Array[String] = []
  ignore(env.schedule(time=2.0, callback=fn() { log.push("A") }))
  ignore(env.schedule(time=1.0, callback=fn() { log.push("B") }))
  env.run()
  assert_eq(log[0], "B")
  assert_eq(log[1], "A")
}

#
SimulationEnv::schedule

source
fn SimulationEnv::schedule(self : SimulationEnv, time~ : Double, priority? : Int, callback~ : () -> Unit) -> Event

调度一个事件在指定时间触发

返回创建的事件对象，可用于后续等待或取消。

#
SimulationEnv::snapshot

source
fn SimulationEnv::snapshot(self : SimulationEnv) -> EnvSnapshot

捕获环境当前状态快照

#
SimulationEnv::step

source
fn SimulationEnv::step(self : SimulationEnv) -> Bool

单步推进：处理下一个事件（用于调试和插件控制）

#
SimulationEnv::timeout

source
fn SimulationEnv::timeout(self : SimulationEnv, duration : Double) -> Event

创建一个超时事件：在当前时间 + duration 后触发

Example

test {
  let env = @core.new_env(until=10.0)
  let ev = env.timeout(5.0)
  inspect(ev.time, content="5")
  inspect(ev.is_pending(), content="true")
}

#
new_env

source
fn new_env(until~ : Double) -> SimulationEnv

创建仿真环境，指定仿真终止时间

Example

test {
  let env = @core.new_env(until=100.0)
  inspect(env.now(), content="0")
  inspect(env.until, content="100")
}

#
new_event

source
fn new_event(id~ : Int, time~ : Double, priority? : Int, callback~ : () -> Unit) -> Event

创建新事件

#
new_queue

source
fn new_queue() -> EventQueue

创建空事件队列

#
new_queue_with_capacity

source
fn new_queue_with_capacity(capacity : Int) -> EventQueue

创建带容量提示的事件队列

预分配数组容量以减少动态扩容开销，适用于大规模仿真场景。

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io