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

module-cycle

Level: warn · Article: Dependencies

Layers point one way. If the crate exposes A, and A uses B, then B does not use A.

What it checks

Two modules of the same crate that depend on each other, directly or through others: ffi uses worker, and worker uses a type from ffi. A dependency is a path into another module of the crate (use crate::a::B, super::B, self::a::B, or a::B for a child module a). Re-exports are followed to where the item is defined, so crate::ApiResult counts as a dependency on ffi when the root only re-exports it with pub use ffi::*.

Modules are compared with their siblings: ffi::error depending on worker is ffi depending on worker. A module’s own items count as a sibling of its children, so a crate root that uses worker while worker uses a type alias defined in lib.rs is a cycle too. A re-export (pub use) is not a dependency of the module that re-exports: exposing a module is not using it. Test code is left out.

The rule reads the whole crate, following mod declarations from src/lib.rs, src/main.rs and src/bin/, even when only some files are being checked. It reports each dependency that closes a cycle, so both ends of a two-module cycle get a diagnostic.

Don’t

#![allow(unused)]
fn main() {
// The FFI layer: what the crate exposes to Kotlin and Swift.
mod ffi {
    use crate::worker::Worker;

    pub type ApiResult<T> = Result<T, ApiError>;

    pub struct ApiError;

    pub struct Client {
        worker: Worker,
    }
}

// The engine the FFI layer drives, reaching back up for its error type.
mod worker {
    use crate::ffi::ApiResult;

    pub struct Worker;

    impl Worker {
        pub fn run(&self) -> ApiResult<()> {
            Ok(())
        }
    }
}
}

worker cannot be used, tested or bound again (to WASM, to a CLI) without dragging the FFI layer along, and the FFI layer is no longer a thin translation: it now holds a type the engine is built on. Nothing marks where one ends and the other begins.

Do

#![allow(unused)]
fn main() {
// The FFI layer translates; it owns nothing the engine needs.
mod ffi {
    use crate::worker::{Worker, WorkerError};

    pub struct ApiError;

    impl From<WorkerError> for ApiError {
        fn from(_: WorkerError) -> Self {
            ApiError
        }
    }

    pub struct Client {
        worker: Worker,
    }
}

// The engine speaks its own errors and knows nothing about who calls it.
mod worker {
    pub struct Worker;

    pub struct WorkerError;

    impl Worker {
        pub fn run(&self) -> Result<(), WorkerError> {
            Ok(())
        }
    }
}
}

The lower layer returns its own types; the upper one wraps them. Dependencies point one way, and each layer can be understood, and replaced, from below.

Silence it

An exception on the dependency you accept removes it from the graph, which breaks the cycle for both ends:

#![allow(unused)]
fn main() {
// Deliberate, until ADS-231 moves it: the callback registry is shared with the FFI layer.
use crate::ffi::CallbackRegistry;
}