nimschedule

01简介

nimschedule 是一个为 Nim 语言设计的轻量级任务调度库，灵感来自 Python 的 schedule 库，但充分利用了 Nim 语言的特性：

02安装

方式一：Nimble 安装

# 在项目目录中
nimble install nimschedule

方式二：直接引用源码

将 src/nimschedule/ 目录复制到你的项目中，然后在编译时指定路径：

# 编译时指定路径
nim c --path:src main.nim

编译要求

nim c -r --threads:on --path:src your_app.nim

03快速开始

30 秒上手 nimschedule：

import nimschedule
import std/os

# 注册一个每 2 秒运行的任务
schedule.every(2).seconds.perform:
  echo "Hello from nimschedule!"

# 主循环
while true:
  schedule.runPending()
  sleep(1000)

proc job() = echo "working"
schedule.every(10).seconds.perform(job)

schedule.every(10).seconds.perform() do:
  echo "working"

schedule.every(10).seconds.perform:
  echo "working"

schedule.every(10).seconds.perform(proc() =
  echo "working"
)

04基本调度

使用 every(N) 设置间隔数量，然后链式调用时间单位：

# 每 10 秒
schedule.every(10).seconds.perform() do:
  echo "每10秒"

# 每 5 分钟
schedule.every(5).minutes.perform() do:
  echo "每5分钟"

# 每 2 小时
schedule.every(2).hours.perform() do:
  echo "每2小时"

# 每 3 天
schedule.every(3).days.perform() do:
  echo "每3天"

# 每 2 周
schedule.every(2).weeks.perform() do:
  echo "每2周"

单数形式

every() 不传参数时默认为 1，此时可以用单数形式（语义更清晰）：

# 等价于 every(1).seconds
schedule.every().second.perform(job)
schedule.every().minute.perform(job)
schedule.every().hour.perform(job)
schedule.every().day.perform(job)
schedule.every().week.perform(job)

05指定时间 at()

at() 方法用于指定任务运行的具体时间点。格式取决于时间单位：

# 每天 10:30 运行
schedule.every().day.at("10:30").perform(job)

# 每天 10:30:00 精确到秒
schedule.every().day.at("10:30:00").perform(job)

# 每小时第 30 分钟运行
schedule.every().hour.at(":30").perform(job)

# 每小时第 15 分 30 秒
schedule.every().hour.at(":15:30").perform(job)

# 每分钟第 15 秒
schedule.every().minute.at(":15").perform(job)

06星期调度

使用星期方法来设置每周特定日期运行的任务：

# 每周一早上 9:00
schedule.every().monday.at("09:00").perform() do:
  echo "周一早会"

# 每周五下午 5:00
schedule.every().friday.at("17:00").perform() do:
  echo "周五周报"

# 每 2 周的周三
schedule.every(2).wednesday.perform() do:
  echo "双周三任务"

# 每周六和周日（分别注册）
schedule.every().saturday.perform(weekendJob)
schedule.every().sunday.perform(weekendJob)

07随机间隔 to()

to() 方法设置间隔的上限，任务将在 interval 到 latest 之间随机运行。适用于需要避免任务扎堆的场景。

import std/random

# 初始化随机种子
randomize()

# 每 5-10 秒之间随机运行
schedule.every(5).to(10).seconds.perform() do:
  echo "随机执行"

# 每 1-3 分钟之间随机运行
schedule.every(1).to(3).minutes.perform() do:
  echo "随机分钟任务"

08截止时间 until()

until() 方法设置任务的截止时间，到期后任务自动取消。支持三种参数类型：

字符串格式

# 今天 23:59 截止
schedule.every().minute.until("23:59").perform(job)

# 指定日期截止
schedule.every().hour.until("2025-12-31").perform(job)

# 指定日期时间截止
schedule.every().minute.until("2025-12-31 23:59:59").perform(job)

Time 对象

import std/times

# 1 小时后截止
let deadline = getTime() + initDuration(hours = 1)
schedule.every().minute.until(deadline).perform(job)

Duration 对象

# 从现在起 30 秒后截止
schedule.every(5).seconds.until(initDuration(seconds = 30)).perform() do:
  echo "30秒内每5秒运行"

09标签管理

使用 tag() 为任务添加标签，便于分组管理和批量操作：

# 添加单个标签
schedule.every().hour.perform(cpuMonitor).tag("monitor")

# 添加多个标签
schedule.every().hour.perform(memMonitor).tag("monitor", "memory")
schedule.every().day.perform(dailyReport).tag("report", "daily")

# 按标签查询
let monitorJobs = schedule.getJobs("monitor")
echo "监控任务数: ", monitorJobs.len

# 按标签清除
schedule.clear("monitor")  # 只清除带 monitor 标签的任务

# 按标签查询下次运行时间
let nextReport = schedule.nextRun("report")

10取消任务

方式一：通过 cancelJob()

let myJob = schedule.every().second.perform(job)

# 立即从调度器中移除
schedule.cancelJob(myJob)

方式二：通过 job.cancel()

let oneShot = schedule.every().second.perform(job)

# 标记为运行后取消（下次运行后自动移除）
oneShot.cancel()

方式三：清除所有任务

# 清除所有任务
schedule.clear()

# 清除特定标签的任务
schedule.clear("monitor")

11错误处理

nimschedule 内置错误处理机制。当任务抛出异常时，不会中断调度器，而是调用错误回调：

# 设置全局错误处理器
schedule.onError(proc(e: ref Exception) =
  echo "任务出错: ", e.msg
  # 可以记录日志、发送通知等
)

# 即使这个任务会抛异常，也不会影响其他任务
schedule.every().second.perform() do:
  raise newException(ValueError, "模拟错误")

# 这个任务照常运行
schedule.every().second.perform() do:
  echo "我正常运行"

12后台执行

这是 nimschedule 相比 Python schedule 的重大改进。无需手写 while True 循环，一行代码启动后台调度：

import nimschedule

# 注册任务
schedule.every(1).seconds.perform() do:
  echo "后台运行中..."

# 启动后台调度线程（每 500ms 检查一次）
startBackground(500)

# 主线程可以做其他事情
echo "主线程自由运行"
sleep(5000)  # 模拟主线程工作

# 停止后台调度
stopBackground()

检查后台状态

if isBackgroundRunning():
  echo "后台调度正在运行"
else:
  echo "后台调度已停止"

13多调度器实例

nimschedule 支持创建多个独立的调度器实例，互不干扰：

import nimschedule
import std/locks

# 创建独立调度器
let workSched = Scheduler(jobs: @[])
initLock(workSched.lock)

let homeSched = Scheduler(jobs: @[])
initLock(homeSched.lock)

# 工作调度器
workSched.every().hour.perform() do:
  echo "[工作] 每小时检查"

# 家庭调度器
homeSched.every().day.at("20:00").perform() do:
  echo "[家庭] 晚上提醒"

# 独立运行
echo workSched.jobCount()  # 1
echo homeSched.jobCount()  # 1
echo schedule.jobCount()  # 0（默认调度器不受影响）

# 各自独立运行
workSched.runPending()
homeSched.runPending()

14Nim 风格直接调用

除了 schedule.xxx 风格，nimschedule 还提供了全局便捷函数，更符合 Nim 的直接调用风格：

import nimschedule

# 不需要 schedule 前缀
discard every(2).seconds.perform(job)

# 直接调用便捷函数
runAll()           # 运行所有任务
runPending()      # 运行到期任务
echo jobCount()    # 任务数量
clear()            # 清除所有
clear("tag")      # 按标签清除

schedule.every(10).seconds.do(job)
schedule.run_pending()
schedule.clear()

every(10).seconds.perform(job)
runPending()
clear()

15API 参考

Job 方法（链式 API）

Scheduler 方法

类型定义

type
  TimeUnit* = enum
    tuNone, tuSecond, tuMinute, tuHour, tuDay, tuWeek,
    tuMonday, tuTuesday, tuWednesday, tuThursday,
    tuFriday, tuSaturday, tuSunday

  JobAction* = proc() {.closure.}

  Job* = ref object
    interval*: int
    latest*: int
    unit*: TimeUnit
    atTime*: string
    tags*: HashSet[string]
    action*: JobAction
    nextRun*: Time
    lastRun*: Time
    untilTime*: Option[Time]
    cancelAfterRun*: bool

  Scheduler* = ref object
    jobs*: seq[Job]
    onErrorCb*: ErrorHandler
    bgRunning*: bool
    bgThread*: Thread[void]
    lock*: Lock

16与 Python schedule 对比

import schedule
import time

def job():
    print("working")

schedule.every(10).seconds.do(job)
schedule.every().day.at("10:30").do(job)

while True:
    schedule.run_pending()
    time.sleep(1)

import nimschedule

schedule.every(10).seconds.perform() do:
  echo "working"

schedule.every().day.at("10:30").perform() do:
  echo "daily"

# 无需 while 循环！
startBackground(1000)

功能对比

17Nim 优势

性能对比