Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Embedding from other languages

cronoq can run inside a program written in Go, Swift, C, or any other language that can call C: no server, no port, no second process. This is for programs that need a scheduler of their own and cannot run a server next to them, such as a desktop or phone app with a local queue of uploads and messages to send.

Experimental until cronoq 1.0. The C API has a version number (cronoq_abi_version()), and it will change before 1.0.

There is one C library, cronoq_ffi, with a header, cronoq.h. On top of it are two wrappers that are maintained with it and behave alike:

LanguagePackageHow it reaches the library
C and otherscronoq.hLinks the static or the dynamic library.
Gogithub.com/synaptiai/cronoq/sdks/go-embedBy default loads the dynamic library at run time, without cgo. With the build tag cronoq_static, links the static library with cgo.
Swiftsdks/swift (package Cronoq)Links the static library.

Rust programs use the cronoq crate and Python programs the cronoq package directly; they do not need this.

How it works

The scheduler runs inside the library, on one thread that the library owns. (The SQLite store, if used, adds threads of its own.) Your program does two things:

  1. It submits tasks. A task is a payload of bytes that only your program understands, plus options: priority, key, ordering key, deadline, and so on.
  2. It runs them. Your threads ask for work with a blocking call, next lease, do the work, and report the result: complete, fail, or release.

Nothing in the library ever calls back into your program.

A lease is one attempt of one task. It ends when you report its result, or when the scheduler ends it: the attempt ran longer than its timeout, or the task was cancelled.

The task is chosen when a thread asks for it. A pool hands out as many attempts as there are threads asking, so a task that is submitted later with a higher priority is still handed out first, as long as nobody has taken the earlier one. There is one exception, described under What to know: a task can already be started when a waiting thread gives up.

Getting the library

Each release from 0.3.0 on has an archive per platform, cronoq-embed-v<version>-<target>.tar.gz (.zip on Windows; for example cronoq-embed-v0.3.0-x86_64-unknown-linux-gnu.tar.gz), with the dynamic library, the static library and the header:

PlatformTargetDynamic library
Linux x86-64, ARM64x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnulibcronoq_ffi.so
macOS x86-64, ARM64x86_64-apple-darwin, aarch64-apple-darwinlibcronoq_ffi.dylib
Windows x86-64x86_64-pc-windows-gnucronoq_ffi.dll
Windows ARM64aarch64-pc-windows-msvccronoq_ffi.dll

The Windows x86-64 library is built with the GNU toolchain, because that is what Go's cgo links with. The Windows ARM64 library is built with MSVC: its dynamic library works with the Go wrapper's default mode, and its static library (cronoq_ffi.lib) is for MSVC, not for cgo.

Each archive, and the binary framework for Swift, comes in two variants:

VariantRelease filesTasks are kept
Without a storecronoq-embed-v<version>-<target>, CCronoq.xcframework.zipIn memory. The smallest library.
With the SQLite storecronoq-embed-sqlite-v<version>-<target>, CCronoq-sqlite.xcframework.zipIn memory, or in a SQLite file if the configuration names one (below).

To build it yourself you need a Rust toolchain:

cargo build --release -p cronoq-ffi
# target/release/libcronoq_ffi.{so,dylib,a}   and   crates/cronoq-ffi/include/cronoq.h
Build featureDefaultAdds
sqliteoffA durable store in a SQLite file (below).
crononRecurring schedules. Without it no schedule can be added. About 0.1 MB.
tzoffTime-zone data, for schedules in a time zone other than UTC. It about doubles the size of the library (on Linux, stripped: 1.9 MB without, 3.8 MB with). The published libraries and frameworks do not have it: their schedules run in UTC.

C

#include "cronoq.h"

cronoq_scheduler *s;
if (cronoq_new(NULL, &s) != CRONOQ_OK) {          /* NULL: one pool, "default" */
  fprintf(stderr, "%s\n", cronoq_last_error());
  return 1;
}

const char *payload = "send event 17";
cronoq_submit(s, (const uint8_t *)payload, strlen(payload),
              "{\"priority\": \"high\", \"ordering_key\": \"chat-1\"}", NULL, NULL);

cronoq_lease lease;
switch (cronoq_next_lease(s, NULL, 5000, &lease)) {    /* waits up to 5 s */
case CRONOQ_OK:
  if (send(lease.payload, lease.payload_len))
    cronoq_complete(s, lease.lease, NULL, 0);          /* no output */
  else
    cronoq_fail(s, lease.lease, "relay refused", /*retryable*/ 1, /*retry_after_ms*/ -1);
  cronoq_lease_free(&lease);
  break;
case CRONOQ_TIMEOUT:  break;                           /* nothing to do: ask again */
case CRONOQ_PAUSED:   printf("paused: %s\n", cronoq_last_error()); break;
case CRONOQ_SHUTDOWN: return 0;
default:              fprintf(stderr, "%s\n", cronoq_last_error());
}

cronoq_shutdown(s, 1000);
cronoq_free(s);
cc -I include app.c libcronoq_ffi.a -lpthread -ldl -lm -o app                      # Linux
cc -I include app.c libcronoq_ffi.a -o app                                         # macOS
gcc -I include app.c libcronoq_ffi.a -lkernel32 -lntdll -luserenv -lws2_32 -ldbghelp -lsynchronization -o app.exe   # Windows (MinGW)

A complete program is in crates/cronoq-ffi/examples/c/example.c.

Go

import embedded "github.com/synaptiai/cronoq/sdks/go-embed"

s, err := embedded.Open(embedded.Config{})
if err != nil { log.Fatal(err) }
defer s.Close()

s.Submit([]byte("send event 17"), &embedded.Task{
    Priority: embedded.High, OrderingKey: "chat-1",
})

for {
    lease, err := s.Next("", 5*time.Second)
    switch {
    case errors.Is(err, embedded.ErrTimeout):
        continue
    case errors.Is(err, embedded.ErrPaused):
        continue // err says why; Next has already waited
    case errors.Is(err, embedded.ErrShutdown):
        return
    case err != nil:
        log.Fatal(err)
    }
    if err := send(lease.Payload); err != nil {
        lease.Fail(err.Error(), true, 0)
    } else {
        lease.Complete()
    }
}

The two build modes have the same API and the same behaviour:

DefaultBuild tag cronoq_static
cgoNot needed (CGO_ENABLED=0 works).Needed, with a C toolchain (MinGW on Windows).
What ships with your programYour binary and the dynamic library.Your binary only.
Where the library is foundAt run time: the path in CRONOQ_LIBRARY, else next to the executable, else by the system's search rules. embedded.Load(path) loads it from a path you choose.At build time: CGO_LDFLAGS="-L<dir>", where <dir> holds libcronoq_ffi.a and not the dynamic library, or the linker prefers that.
Cost per callAbout three times that of cgo; both are far below a millisecond.

Each goroutine inside Next holds an operating system thread while it waits.

A complete program is in sdks/go-embed/example.

Swift

import Cronoq
import Foundation

let scheduler = try Scheduler()
try scheduler.submit(Data("send event 17".utf8), TaskOptions(priority: .high, orderingKey: "chat-1"))

while true {
    do {
        let lease = try scheduler.next(timeout: 5)
        do {
            try send(lease.payload)
            try lease.complete()
        } catch {
            try lease.fail("\(error)")
        }
    } catch CronoqError.timeout {
        continue
    } catch CronoqError.paused(let reason) {
        print("paused: \(reason)")
    } catch CronoqError.shutdown {
        break
    } catch {
        print("error: \(error)")
        break
    }
}

next blocks its thread: call it from a thread of your own, not from the main thread and not from Swift's cooperative thread pool.

The package links the static library. Build the library and tell the linker where it is:

cargo build --release -p cronoq-ffi
swift build -Xlinker -L<dir with libcronoq_ffi.a>

For iOS, and to do without a Rust toolchain, each release from 0.3.0 on has a binary framework, CCronoq.xcframework.zip, with the static library for iOS devices (ARM64), the Apple-silicon iOS simulator and macOS (ARM64 and x86-64), and its checksum. CCronoq-sqlite.xcframework.zip is the same with the SQLite store. Copy sdks/swift into your project, delete Sources/CCronoq, and replace the CCronoq target in Package.swift:

.binaryTarget(
    name: "CCronoq",
    url: "https://github.com/synaptiai/cronoq/releases/download/v<version>/CCronoq.xcframework.zip",
    checksum: "<contents of CCronoq.xcframework.zip.checksum>"
),

The release workflow builds the framework and runs the package's tests against it in this form.

Configuration

cronoq_new takes a JSON object; the wrappers build it from a Config value. Every field is optional, and an unknown field is an error.

{
  "pools": [{
    "name": "default",
    "max_leases": 256,
    "max_pending": 10000,
    "overflow": "reject",
    "retry": {"max_attempts": 3, "initial_backoff_ms": 1000, "multiplier": 2.0,
              "max_backoff_ms": 60000, "jitter": true},
    "max_releases": 10,
    "lease_ttl_ms": 30000,
    "priority": {"aging_rate": {"low": 0.5}},
    "urgency": {"window_s": 60},
    "fairness": {"weights": {"paying": 3}, "default_weight": 1},
    "unknown_dependency": {"await": true, "timeout_ms": 60000},
    "label_grace_ms": 1000
  }],
  "resources": [{"kind": "semaphore", "name": "uplink", "permits": 1},
                {"kind": "rate", "name": "relay", "rate": 5.0, "burst": 10}],
  "priority": {"base": {"critical": 1000}, "allow_overtaking_high": false},
  "urgency": {"max": 100, "window_s": 300},
  "store": {"sqlite": "/path/to/queue.db"},
  "events": "final"
}
FieldMeaning
poolsThe pools. Without it there is one pool, default.
pools[].max_leasesMost attempts your program may hold at a time (default 256).
pools[].max_pending, overflowA bound on the queue and what a full queue does: reject (default), shed_lowest or shed_oldest. A submission never blocks.
pools[].retryThe retry policy of the pool's tasks.
pools[].max_releasesHow often an attempt of one task may be released without counting as a failure.
pools[].lease_ttl_msLeases expire unless they are extended with a heartbeat within this time. Without it a lease lasts until its result is reported or its task's timeout.
pools[].fairnessFair sharing of the pool between the tenants of its tasks: weights by tenant, and default_weight (default 1) for every other tenant and for tasks without one.
pools[].unknown_dependencyWhat happens to a task that waits for a key no task has. By default the submission is refused. With {"await": true} the task waits for a task with that key, for ever or for timeout_ms, after which it is skipped.
pools[].label_grace_msHow long an attempt of a task with labels waits for a thread that carries them before it is given back (default 1000, at least 10).
priority, urgencyThe priority and urgency settings, for all pools or for one. Classes are named critical, high, normal, low.
resourcesSemaphores and rate limits that tasks name in their resources.
store.sqliteKeep tasks in this SQLite file. Needs a library built with sqlite.
eventsWhich status events subscriptions get: final (default) or all.

Task options

cronoq_submit takes the payload and a JSON object of options; the wrappers build it from a value (Task in Go, TaskOptions in Swift). Every field is optional, and an unknown field is an error.

OptionMeaning
poolThe pool (default default).
kindA name for the kind of work, for your own use and for statistics.
keyA key: a second submission with the key of a live task returns that task.
prioritycritical, high, normal (default) or low. See Priorities and aging.
deadline_msA deadline that far from now.
timeout_msAn attempt that runs longer is ended and counts as a failure.
retryA retry policy for this task.
resourcesAmounts of resources the task needs, by name.
tagsText you get back with the lease.
ordering_key, on_failureOrdering keys: tasks with one key run one at a time, in submission order. on_failure is continue (default) or halt.
on_key_conflictreturn_existing (default), reject, or replace_queued to replace the queued task with this key.
fingerprint, with on_key_conflict: reject1 to 32 hexadecimal digits that stand for the content. A submission whose key belongs to a task with another fingerprint is a conflict.
renew_positionA replacement goes to the back of the queue instead of keeping the place.
max_releasesOverrides the pool's limit for this task.
start_in_ms, start_at_unix_msA fixed start: that far from now, or at a time in milliseconds since 1970 UTC. Give at most one. The task is not handed out before it.
start_tolerance_ms, on_missHow late a fixed start may be and still be on time (default 1000), and what a later one does: run_late (default), skip or fail.
duration_hint_msHow long an attempt is expected to run, until the scheduler has seen tasks of this kind.
afterTasks this one waits for. Each entry is a task id, a key, or {"task": id} or {"key": "..."} with "when": success (default), complete (any outcome) or failure. A task whose dependency can no longer be met is skipped.
tenantWho the task belongs to, for a pool with fairness.
labelsLabels a thread must carry to get the task.

A fixed start needs a thread that asks for a lease at that time: the scheduler hands the task to the next thread that asks once the start has come. It keeps a slot free for the task shortly before the start, so with a single thread other work can be held back for about as long as the scheduler expects that work to run (one second until it has seen the kind; duration_hint_ms tells it).

Recurring schedules

A recurring schedule submits a task at each time a cron expression names. The expression has five fields (minute, hour, day of month, month, day of week), or six with seconds first.

cronoq_schedule_add(s, "sync", "*/5 * * * *", (const uint8_t *)"sync", 4,
                    "{\"overlap\": \"skip\", \"task\": {\"kind\": \"sync\", \"priority\": \"low\"}}");
err := s.AddSchedule("sync", "*/5 * * * *", []byte("sync"),
    &embedded.Schedule{Overlap: "skip", Task: &embedded.Task{Kind: "sync", Priority: embedded.Low}})
try scheduler.addSchedule(
    name: "sync", cron: "*/5 * * * *", payload: Data("sync".utf8),
    ScheduleOptions(overlap: "skip", task: TaskOptions(kind: "sync", priority: .low)))
OptionMeaning
tzThe IANA time zone of the expression. UTC when left out. A zone other than UTC needs a library built with the tz feature; the published libraries refuse it.
overlapWhat happens while the previous occurrence is not done: skip (default), allow, queue (run after it) or queue_on_success (run after it if it succeeded).
tolerance_ms, on_missHow late an occurrence may start and still be on time, and what a later one does: run_late (default), skip or fail.
taskThe options of each occurrence, as for a submission. A key is a prefix: each occurrence gets <key>@<its start in UTC>. deadline_ms counts from the occurrence's start. A fixed start, after and a replacing on_key_conflict describe one task and are refused.
  • Adding a schedule with a name that exists replaces it. Remove one with cronoq_schedule_remove (Go RemoveSchedule, Swift removeSchedule); list them with cronoq_schedules (Go Schedules, Swift schedules).
  • Schedules are kept where tasks are kept. In memory they are gone when the program ends: add them again at every start. With the SQLite store they are kept, and adding one again replaces it, so the same start-up code is right in both cases.
  • Nothing runs while the program does not. An occurrence is a task with a fixed start, and a task needs a thread that asks for it. Without a store, occurrences that fell into the time the program was not running are not made up. On a phone, call the clock resynchronisation when the app becomes active, or the schedule is late by the time slept.

Labels

A task with labels goes only to a thread that carries all of them. The thread says which labels it has when it asks for a lease:

cronoq_next_lease_labeled(s, NULL, "{\"network\": \"wifi\"}", 5000, &lease);
lease, err := s.NextLabeled("", map[string]string{"network": "wifi"}, 5*time.Second)
let lease = try scheduler.next(labels: ["network": "wifi"], timeout: 5)
  • A task without labels goes to any thread. The scheduler prefers threads with fewer labels for it, so labelled threads stay free for the work only they can do.
  • cronoq_next_lease is the same call without labels.
  • The lease carries the labels its task requires.
  • Use a few lasting labels. Threads that pass the same labels form a group, and a pool keeps at most 64 different groups for the life of the scheduler; a call with one more set of labels is an error. A label is for a property such as "has Wi-Fi", not for a value that keeps changing, such as a battery level.
  • The labels are a statement about the thread at the time it asks. To stop taking work that needs a label (the device left Wi-Fi), ask without it.
  • max_leases holds for all groups of a pool together. Your program never holds more attempts than that. When threads of several groups wait and the pool is at its limit, the scheduler may start one attempt more per group than there are leases free. Such an attempt is handed out as soon as a lease is free; its timeout runs from its start.
  • An attempt nobody with its labels asks for is given back. The scheduler can start a task for a thread a moment after that thread stopped waiting. If the task has no labels, the next thread of the pool takes it. If it has labels and no thread with them asks within the pool's label_grace_ms (default one second), the attempt is released: the task goes back to the queue and waits for such a thread. This counts toward the task's max_releases, so make label_grace_ms longer than the longest pause between two calls of a thread with labels.

Operations

OperationCGoSwift
Start, stopcronoq_new, cronoq_shutdown, cronoq_freeOpen, Shutdown, CloseScheduler(), shutdown, release of the last reference
Submitcronoq_submitSubmitsubmit
Take an attemptcronoq_next_lease, cronoq_lease_freeNextnext
Take an attempt as a thread with labelscronoq_next_lease_labeledNextLabelednext(labels:)
Recurring schedulescronoq_schedule_add, cronoq_schedule_remove, cronoq_schedulesAddSchedule, RemoveSchedule, SchedulesaddSchedule, removeSchedule, schedules
Reportcronoq_complete, cronoq_fail, cronoq_releaseLease.Complete, Fail, ReleaseLease.complete, fail, release
Extend a leasecronoq_heartbeatLease.HeartbeatLease.heartbeat
Cancelcronoq_cancelCancelcancel
Update a queued taskcronoq_updateUpdateupdate
Floor of an ordering keycronoq_set_ordering_floorSetOrderingFloorsetOrderingFloor
Pause, resumecronoq_pause, cronoq_resumePause, Resumepause, resume
Report with a resultcronoq_complete with output bytesLease.CompleteWithOutputLease.complete(output:)
Wait for a resultcronoq_waitWaitwait
Status eventscronoq_events_open, cronoq_events_next, cronoq_events_closeEvents, Events.Next, Events.Closeevents(), EventStream.next
Lookcronoq_task, cronoq_snapshotTask, Snapshottask, snapshot
Time after sleepcronoq_resync_clock, cronoq_advance_clockResyncClock, AdvanceClockresyncClock, advanceClock
Versioncronoq_abi_version, cronoq_versionVersionScheduler.libraryVersion

Three results end an attempt:

Use it whenWhat happens
CompleteThe work is done.The task succeeds.
FailThe work failed.Retryable: tried again after a backoff until the retry policy is used up. Not retryable: the task fails for good.
ReleaseYou cannot run the task now, and nothing is wrong with it (no network, the app is going to the background).The task keeps its place and is handed out again after the delay. No retry is used, up to max_releases.

Results and events

The part of your program that submits a task is often not the part that runs it. Two calls connect them.

A result. An attempt can be completed with an output: bytes that only your program understands, like the payload. Wait blocks until the task has ended, up to a timeout, and returns how it ended.

The taskWait returns
succeeded"Succeeded" and the output (empty if none was given).
ended in another way"Not succeeded" and text: the final status and the message, for example dead_lettered: relay refused or cancelled: ....
has not ended yetTimeout. Call again.
is unknown, or ended too long agoNot found.
r, err := s.Wait(embedded.TaskRef{Key: "upload-17"}, 30*time.Second)
if err == nil && r.Succeeded {
    use(r.Output)
}

Any number of threads may wait for one task. The scheduler keeps the results of the last 1024 tasks that ended; with the SQLite store, older ones are read from the file.

Events. A subscription delivers what happens to tasks, as it happens, to a thread that asks for the next event with a blocking call.

"events" in the configurationEvents you get
"final" (default)One per task, when it ends: succeeded, failed, dead_lettered, cancelled, and so on.
"all"Every change of status (ready, running, retrying, ...), and every update and replacement.
{"task": 7, "key": "k", "pool": "default", "status": "succeeded", "attempt": 1,
 "priority": "normal", "at_unix_ms": 1767225600000, "message": null, "event": "transition"}
  • event is transition (the status changed), updated, replaced or successor.
  • Each subscription gets every event from the moment it was opened. Open it before you submit the tasks you want to follow.
  • The scheduler keeps the last 4096 events for a slow reader. A reader that falls further behind gets {"lagged": n} once, with the number of events it lost, and then goes on with the oldest event that is kept. Events are for showing progress; use wait when you must not miss the end of a task.
  • Events are not stored. After a restart, a subscription starts empty.

What to know

  • Results are applied a moment later. complete, fail and release hand the result to the scheduler's thread and return. A snapshot taken at once may not show it yet.
  • A cancelled task's lease is over when cancel returns. The next heartbeat or report for it answers "lease gone". A long attempt learns of a cancel by sending heartbeats.
  • A paused pool. next lease waits out its timeout and then reports "paused" with the reason, so a loop around it does not spin. A paused class or ordering key is not reported this way: the call just finds nothing of it. See the snapshot for those.
  • A task may be started a moment before a thread asks for it. When a thread stops waiting, or the scheduler ends a lease you hold (timeout, cancel), the scheduler can have started one more task already. That task counts as running, its timeout runs, and it goes to the next thread that asks. Keep asking, or shut down, rather than leaving a pool alone with work in it.
  • Stopping. shutdown wakes the threads that wait and hands out nothing more. For the grace period you give it, leases you hold can still be reported; it returns as soon as all are. A lease that is still held after that is released: its task keeps its place and no retry is used.

Time, sleep and phones

The scheduler reads the wall clock once, when it starts, and then counts on with the clock of the Rust standard library. That clock is monotonic, and on Apple platforms and on Linux it does not count the time the machine sleeps.

EventWhat happens
The wall clock is changed (by the user, or by a time server)Nothing. Backoffs, timeouts and deadlines that are already set keep running as they were.
The machine sleepsNothing runs and no timer fires. After waking, every timer is late by the time slept: a retry that was 30 seconds away is still 30 seconds away.
The app is suspended while the device stays awakeThe clock keeps counting. Timers that became due fire when the app runs again.
The program calls resync clock after wakingThe scheduler's time jumps forward by the time it missed. Timers that became due during the sleep fire at once, all of them; they are not spread out.

Call cronoq_resync_clock (Go ResyncClock, Swift resyncClock) when your program becomes active again:

NotificationCenter.default.addObserver(
    forName: UIApplication.didBecomeActiveNotification, object: nil, queue: nil
) { _ in
    _ = try? scheduler.resyncClock()
}
  • It returns how far the time moved. When nothing was missed it does nothing, so calling it more often than needed is harmless.
  • The sleep is measured with a monotonic clock of the operating system that counts during sleep (CLOCK_MONOTONIC on Apple platforms, CLOCK_BOOTTIME on Linux, the tick count on Windows). A wrong or changed wall clock has no effect.
  • The scheduler's time never moves back.
  • Leases held across the sleep. A lease times out at the resynchronisation if its task has a timeout shorter than the sleep. It expires if its pool has a lease_ttl_ms shorter than the sleep, because nobody could extend it. Both count as a failed attempt and use a retry. Release leases before the app goes to the background if you can (release), or use no timeout and no lease TTL for work that survives a suspension.
  • With the SQLite store, the store's claim on the file uses the wall clock: after a long sleep, or a wall-clock jump forward, the claim has run out. With one program per file nobody else has taken it, and the scheduler simply extends it again.

cronoq_advance_clock (Go AdvanceClock, Swift advanceClock) moves the scheduler's time forward by an amount you choose. It is for tests: a backoff of an hour is over after advance clock (1 hour), without waiting. The scheduler's time then stays ahead of the wall clock, so the times in events are in the future. Do not use it with a store you keep.

The library does not run in the background. While the app is suspended or the device sleeps, no task is handed out and no timer fires. It does not ask the operating system for background time; that is your app's business. What it guarantees is correct behaviour when the app is active again, after the resynchronisation.

Apple platforms

TargetStatus
iOS device, ARM64 (aarch64-apple-ios)Built nightly, for each release, and on pull requests that change the library or the Swift package.
iOS simulator on Apple silicon (aarch64-apple-ios-sim)Built, and tested in the simulator: the engine's simulation tests, the tests of the C API and the clock tests.
macOS ARM64 and x86-64Built and tested on every pull request.
AndroidNot built or tested. Ask in an issue.

Everything in the C API works on iOS: priorities with aging, retries, resources, ordering keys, replace, update, pause, release. Each release has a size report, cronoq-embed-apple-sizes.md, with the stripped size of the library per target, with and without cron and time-zone data, and with the SQLite store. The default build has none of the three. For a queue that survives restarts, use the framework with the SQLite store.

Keeping tasks across restarts

By default tasks are kept in memory: when the program ends, the queue is gone. That suits a program whose own database is the source of truth and that fills the queue again at start.

With a library built with the sqlite feature, "store": {"sqlite": "<path>"} keeps tasks, recurring schedules, pauses and ordering-key settings in that file. After a restart the queue is as it was; an attempt that was running is tried again. One program at a time may have the file open.

Each release from 0.3.0 on has the library with the store as a second variant: cronoq-embed-sqlite-v<version>-<target> and CCronoq-sqlite.xcframework.zip. To build it yourself: cargo build --release -p cronoq-ffi --features sqlite.

Rules of the boundary

These are also at the top of cronoq.h.

Rule
ErrorsEvery function that can fail returns a cronoq_status. Nothing panics or aborts across the boundary: a fault inside the library is CRONOQ_INTERNAL. cronoq_last_error() returns the message of the last failed call on the calling thread, valid until that thread's next call.
TextUTF-8, zero-terminated. The library copies what it is given before the call returns. Your buffers stay yours.
PayloadsOpaque bytes. Copied at submit.
What the library returnsStays the library's until you hand it back: a scheduler to cronoq_free, a lease to cronoq_lease_free, a buffer to cronoq_buf_free. Never to free(). A lease's pointers stay valid until cronoq_lease_free, also after the lease was completed.
ThreadsA scheduler may be used from any number of threads at once. The exception is cronoq_free: every other thread must be out of the library first. Call cronoq_shutdown, which wakes the threads that wait in cronoq_next_lease, then join them, then free.
The library's threadThe scheduler runs on one thread, started by cronoq_new and stopped by cronoq_shutdown. It never calls into your program. The SQLite store, if used, adds threads of its own: one for each database connection it opens.
Versionscronoq_abi_version() must equal the CRONOQ_ABI_VERSION of the header you built with. The number changes when an existing function, structure or constant changes; additions do not change it. The wrappers check it for you.

The Go and Swift wrappers take care of ownership and of the per-thread error message. In Go, Close waits for calls in progress before it frees the scheduler.