Inside the crates

The rules · chapter 07, the style guide

C-like Rust: what the style guide allows and what it forbids

iclaustron: doc/rust/07-style-guide.md (Allowed and encouraged; Forbidden in library code); doc/rust/01-goals-and-principles.md (principle 2); crates/ic_util/src/threadpool.rs (ThreadFunc); crates/ic_capi/src/lib.rs (guarded, on_conn); crates/ic_apid/src/hash.rs (KeyWalk)

The rules · chapter 09, licensing

Clean room: written from the wire, MIT licensed, no RonDB name

iclaustron: doc/rust/09-licensing.md (Facts; Clean-room procedure; Names; Repository); crates/ic_signals/src/numbers.rs (IC_SIG_KEY_OP_REQ); xtask/src/names.rs (module note, SCOPE); Cargo.lock; deny.toml; legacy-c/README.md

The crates · from crates/*/Cargo.toml

The crates' dependencies, as their Cargo.toml files declare them

iclaustron: crates/*/Cargo.toml ([dependencies]); Cargo.toml ([workspace.dependencies]); Cargo.lock (libc); uses counted with grep '<crate>::' in each crate's src/

The crates · where to start reading

What each crate holds, its size, and where to start reading

Lines are wc -l of src/, tests included. Each lib.rs names its modules. MODULE.md maps a crate to its C; ic_apic's, ic_signals' and ic_apid's are still the phase 0 template.

iclaustron: crates/*/src/lib.rs (module notes); crates/*/MODULE.md; crates/ic_capi/src/lib.rs (#[no_mangle] exports); wc -l crates/*/src/*.rs

ic_port · err.rs and ndb_err.rs

IcError is one i32 code; category and severity come from it

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(C)]
pub struct IcError {
  pub code: i32,
}

impl IcError {
  pub fn category(&self) -> ErrorCategory {
    if self.is_ic_error() {
      return ic_class(self.code).0;
    }
    crate::ndb_err::class_of(self.code).category()
  }
  // ... severity(), is_temporary(), message()

iclaustron: crates/ic_port/src/err.rs (IcError, impl IcError, ic_class, IC_FIRST_ERROR, IC_LAST_ERROR, ErrorCategory, ErrorSeverity); ndb_err.rs (ErrorClass, class_of); crates/ic_port/src/lib.rs (module note)

ic_port · sync.rs

IcMutex owns its data and a level; debug builds check the order

pub struct IcMutex<T> {
  level: u32,
  inner: Mutex<T>,
}
fn check_order(level: u32) {
  if level == IC_MUTEX_LEVEL_UNORDERED || !cfg!(debug_assertions) {
    return;
  }
  // ... violated: a level this thread holds, >= level
  if violated != 0 {
    // ... print both levels
    std::process::abort();
  }
}

iclaustron: crates/ic_port/src/sync.rs (IcMutex, check_order, push_level, IcMutexGuard, IcCond::wait, IC_MUTEX_LEVEL_*); crates/ic_port/MODULE.md (Deviations; Rust notes for C readers)

ic_util · ptr_array.rs and mc.rs

PtrArray ids: a 24-bit slot and a 40-bit generation, a 32-bit word on the wire

pub fn remove(&mut self, id: PtrId) -> Option<T> {
  let index = id.index() as usize;
  let slot = self.slots.get_mut(index)?;
  if slot.generation == IC_RETIRED || slot.generation != id.generation() {
    return None;
  }
  let value = slot.value.take()?;
  // ...
  // A slot whose generation would wrap is retired, never used again, ...
  if slot.generation >= IC_MAX_GENERATION {
    slot.generation = IC_RETIRED;
    return Some(value);
  }
  slot.generation += 1;
  self.free_list.push(index as u32);
  Some(value)
}

iclaustron: crates/ic_util/src/ptr_array.rs (module note; PtrId, wire_word, PtrArray::insert, remove, id_of_wire); mc.rs (McHandle); crates/ic_util/MODULE.md (Deviations); crates/ic_capi/src/lib.rs (opening note)

ic_signals · the wire format

ic_signals is the wire alone: no sockets, no threads, no state

/// The eight words of signal data. The column data length, third, is
/// zero: in the long form it is the length of section 1.
pub fn encode(&self) -> [u32; IC_KEY_OP_REQ_LEN] {
  [
    self.coord_ptr,
    self.query_ref,
    0,
    self.table_id,
    self.flags_word,
    self.table_version,
    self.trans_id_lo,
    self.trans_id_hi,
  ]
}

iclaustron: crates/ic_signals/src/key_ops.rs (KeyOpReq::encode); header.rs (decode, Message); lib.rs (module note); interp.rs and scans.rs (tests); doc/rust/08-testing-and-tooling.md (Unit tests)

ic_apid · the module map

ic_apid's 32 files, grouped by the job they do

Every file opens with a //! note; a translated one names its legacy-c/ file. The largest: scan.rs, 3 442 lines; apid_conn.rs, 2 580.

iclaustron: crates/ic_apid/src/lib.rs (module list); the module note of each file; wc -l crates/ic_apid/src/*.rs

ic_apid · receive path

The receive path in code: reader, router, page, inbox, poll

iclaustron: crates/ic_apid/src/signal_reader.rs (SignalReader::read_from, ReceivePage, IC_RECEIVE_PAGE_WORDS); rec_thread.rs (route_signals); signal_page.rs (module note, next); thread_conn.rs (Router::post_all, ThreadConnection::post); apid_conn.rs (poll_with_requests, receive_view)

ic_apid · node_connect.rs and apid_conn.rs

SignalView borrows its words: poll reads signals where they lie

pub struct SignalView<'a> {
  pub sig_no: u16,
  // ... the two blocks, the sending node, fragment_state
  pub data: &'a [u32],
  pub sections: [&'a [u32]; header::IC_MAX_SECTIONS],
  pub num_sections: usize,
}

for page in &pages {
  let mut at: usize = 0;
  while let Some(signal) = signal_page::next(page, &mut at) {
    taken += 1;
    self.receive_view(&signal);
  }
}

iclaustron: crates/ic_apid/src/node_connect.rs (SignalView, to_owned); apid_conn.rs (poll_with_requests, receive_view); signal_page.rs (module note, next); thread_conn.rs (exchange)

ic_apid · apid_conn.rs

ApidConnection: one thread's objects, held with no lock

pub struct ApidConnection {
  pub(crate) shared: Arc<ApidShared>,
  inbox: Arc<ThreadConnection>,
  expectations: Expectations,
  coord_records: Vec<CoordRecord>,
  free_coord: Vec<Vec<u32>>,
  pub(crate) queries: PtrArray<ApidQuery>,
  pub(crate) transactions: PtrArray<Transaction>,
  pub(crate) executed: VecDeque<QueryId>,
  active: Vec<Option<TransId>>,
  outgoing: Vec<Outgoing>,
  pub(crate) scans: PtrArray<Scan>,
  pub(crate) receivers: PtrArray<ReceiverSlot>,
  // ...

iclaustron: crates/ic_apid/src/apid_conn.rs (ApidConnection, CoordRecord, Outgoing, Staged, coord_index_of); executor.rs (Runner, Runner::run)

ic_apid · row_codec.rs and hash.rs

row_codec and hash: a row into words, a key onto a node

Both work on plain slices, rows as &[u8] and words as &[u32]. A wrong node costs a hop in the cluster, never a wrong answer.

iclaustron: crates/ic_apid/src/row_codec.rs (module note, key_info_into, read_attr_info, unpack_row, IC_COL_READ_EVERY, IC_COL_READ_MASKED); hash.rs (module note, distribution_key, partition_hash, choose_node, primary_of); crates/ic_util/src/lib.rs (md5, xxh3)

unsafe · counted with grep

Where unsafe lives: counted per crate, with what it is for

410 blocks, 410 SAFETY: comments. The row path, record.rs, row_codec.rs and query.rs, has no unsafe block: a row is the query's own Vec<u8>.

iclaustron: grep 'unsafe {' and 'SAFETY' in crates/*/src; crates/ic_apid/src/signal_reader.rs (bytes_of, bytes_of_mut); node_connect.rs (words_as_bytes); query.rs (module note); doc/rust/07-style-guide.md (unsafe blocks)

ic_capi · the C ABI

ic_capi exports: a Rust object boxed as a handle, or named by id

#[no_mangle]
pub unsafe extern "C" fn ic_apid_global_create_connection(
  global: *mut IcApidGlobal,
  conn: *mut *mut IcApidConnection,
) -> i32 {
  // ... the null checks, and g: the global
  guarded(|| match g.create_connection() {
    Ok(made) => {
      let handle = Box::into_raw(Box::new(made)) as *mut IcApidConnection;
      // SAFETY: checked non-null above; the caller's promise.
      unsafe { conn.write(handle) };
      0
    }
    Err(e) => e.code,
  })

iclaustron: crates/ic_capi/src/lib.rs (ic_apid_global_create_connection, ic_apid_conn_free, IcApidConnection, guarded); crates/ic_capi/cbindgen.toml; crates/ic_capi/MODULE.md (How a call crosses); xtask/src/main.rs (run_header)

ic_capi · panics and sizes

The C boundary's guards: panics become 7129, short structs refused

unsafe fn on_conn<T, F: FnOnce(&mut ApidConnection) -> T>(
  conn: *mut IcApidConnection,
  f: F,
) -> Result<T, i32> {
  let raw = conn as *mut ApidConnection;
  // ... a null handle: IC_ERROR_NULL_POINTER
  let c = unsafe { &mut *raw };
  if c.is_unusable() {
    return Err(err::IC_ERROR_INTERNAL_PANIC);
  }
  match catch_unwind(AssertUnwindSafe(|| f(c))) {
    Ok(value) => Ok(value),
    Err(_) => {
      unsafe { (*raw).set_unusable() };
      Err(err::IC_ERROR_INTERNAL_PANIC)

iclaustron: crates/ic_capi/src/lib.rs (on_conn, guarded, sized_from_c, get_sized, put_sized); crates/ic_apid/src/apid_conn.rs (set_unusable, is_unusable); crates/ic_capi/cbindgen.toml (Panics; Structs with a size)

Testing · chapter 08, as built

The test pyramid: unit tests, captured words, a live cluster, fuzzing

iclaustron: grep '#[test]' in crates/*/src; crates/ic_apid/tests/integration.rs and crates/ic_capi/tests/c_api.rs (module notes); crates/ic_signals/src/interp.rs (tests), fuzz_tests.rs; crates/ic_port/src/fuzz.rs; tools/scan_capture.sh; xtask/src/main.rs (run_test_integration, run_fuzz); doc/rust/08-testing-and-tooling.md

Tooling · xtask/ and the files at the root

cargo xtask and the checked-in configs: the checks before a commit

cargo xtask check               # fmt, clippy, test, style
cargo xtask style               # 80 columns, forbidden constructs
cargo xtask header              # cbindgen, diffed with the header
cargo xtask test-integration    # against a live cluster
cargo xtask fuzz [target]       # the decoders' fuzz tests
cargo xtask names [rondb-tree]  # no RonDB name in the tree
cargo xtask install [prefix]    # library, header, pkg-config
cargo xtask tags                # vim tags, Rust and legacy-c/

iclaustron: xtask/src/main.rs (print_help, run_check, FORBIDDEN, run_style, run_fuzz); xtask/style-allow.txt; rust-toolchain.toml; rustfmt.toml; Cargo.toml ([workspace.lints], [profile.fuzz]); clippy.toml; deny.toml

Tooling · tools/ic_bench and tools/ic_model

ic_bench measures, ic_model predicts a change before it is built

Both on the author's Mac with two release data nodes on it: allocations counted 2026-10-14, 100 000 keys; the model fitted 2026-09-24.

iclaustron: tools/ic_bench/src/main.rs (module note); alloc_count.rs; doc/rust/06-phases.md (Phase 7, the performance pass); tools/perf_pass.sh; tools/ic_model/src/main.rs; doc/rust/12-performance-model.md (Calibration; Using it)

History · chapter 06, phases

How it was built: translated foundations, then new code by phase

Phases 0 to 5, sized at 20 weeks, were built from 2026-09-18 to 2026-09-25. A translated module keeps the C's file and function names.

iclaustron: doc/rust/06-phases.md (phase table; Replanned 2026-10-08; Working method per module); doc/rust/01-goals-and-principles.md (principles 1 and 11); git log

History · from legacy-c/ to the crates

A worked mapping: post_ndb_messages in C, ThreadConnection::post

ic_mutex_lock(loc_thd_conn->mutex);
/* Link it into list on this thread connection object */
/* ... */
loc_thd_conn->last_received_message= last_ndb_message_page;
if (loc_thd_conn->thread_wait_cond)
{
  loc_thd_conn->thread_wait_cond= FALSE;
  signal_flag= TRUE;
}
ic_mutex_unlock(loc_thd_conn->mutex);
/* END Critical Section with delayed wake up signal */
if (signal_flag)
{
  ic_cond_signal(loc_thd_conn->cond);
}

let mut inbox = self.inbox.lock();
if inbox.closed {
  page.clear();
  return false;
}
let fresh = inbox.spare.pop().unwrap_or_default();
let full = std::mem::replace(page, fresh);
inbox.pages.push(full);
let wake = inbox.waiting;
inbox.waiting = false;
// Unlock, and only then wake; see the note at the top of the file.
drop(inbox);
if wake {
  self.cond.signal();
}

The same order: lock, append, note a sleeper, unlock, then wake. The unlock is drop(inbox); the list of pages is a Vec, a spare swapped in.

iclaustron: legacy-c/api/ic_apid_rec_thread.ic (post_ndb_messages); crates/ic_apid/src/thread_conn.rs (module note, ThreadConnection::post); doc/rust/11-c-to-rust-mappings.md (Threads and synchronisation); doc/rust/03-module-map.md

Recap · module 09

Inside the crates: what to take away

• C-like Rust, from the wire in a clean room: no trait of our own, nothing async.
• Eight crates, no cycle: the rest all use ic_port, ic_signals nothing else; libc is the one from outside.
• Errors are one i32; mutexes carry levels; queries, transactions, scans are ids with a generation.
• Replies go reader, router, page, inbox, poll, and are read in place as a SignalView.
• unsafe sits at the edges, 410 blocks with as many SAFETY notes; the row path has none.
• The C ABI boxes objects as handles and turns a panic into 7129.

iclaustron: doc/rust/07-style-guide.md; doc/rust/09-licensing.md; crates/*/Cargo.toml; crates/ic_port/src (err.rs, sync.rs); crates/ic_util/src/ptr_array.rs; crates/ic_apid/src; crates/ic_capi/src/lib.rs

iClaustron training for Rust developers · 9 modules · you are at 09

End of the iClaustron training · back to 01