API Reference

Relevant source files

• src/lib.rs

This document provides complete reference documentation for the CpuMask<SIZE> struct and its associated types, methods, and trait implementations. The API enables efficient CPU affinity management through bitset operations optimized for different CPU count scenarios.

For architectural details and storage optimization strategies, see Architecture and Design. For practical usage examples and common patterns, see Usage Guide and Examples.

Core Types and Structure

The cpumask library centers around the CpuMask<const SIZE: usize> generic struct, which provides a compile-time sized bitset for representing CPU sets.

flowchart TD
subgraph subGraph3["Iterator Interface"]
    G1["IntoIterator trait"]
    G2["Iter<'a, SIZE>"]
    G3["Iterator + DoubleEndedIterator"]
end
subgraph subGraph2["Query Operations"]
    D1["get(index)"]
    D2["len()"]
    D3["is_empty()"]
    D4["is_full()"]
    D5["first_index()"]
    D6["last_index()"]
    D7["next_index(index)"]
    D8["prev_index(index)"]
    D9["*_false_index variants"]
end
subgraph subGraph1["Construction Methods"]
    C1["new()"]
    C2["full()"]
    C3["mask(bits)"]
    C4["from_value(data)"]
    C5["from_raw_bits(value)"]
    C6["one_shot(index)"]
end
subgraph subGraph0["Core API Structure"]
    A["CpuMask<SIZE>"]
    B["Bitmap<SIZE> value"]
    C["Construction Methods"]
    D["Query Operations"]
    E["Modification Methods"]
    F["Bitwise Operations"]
    G["Iterator Interface"]
end

A --> B
A --> C
A --> D
A --> E
A --> F
A --> G
C --> C1
C --> C2
C --> C3
C --> C4
C --> C5
C --> C6
D --> D1
D --> D2
D --> D3
D --> D4
D --> D5
D --> D6
D --> D7
D --> D8
D --> D9
G --> G1
G --> G2
G --> G3

Sources: src/lib.rs(L18 - L23)  src/lib.rs(L68 - L235) 

Type Definitions and Constraints

The storage type is automatically optimized based on the SIZE parameter:

Sources: src/lib.rs(L12 - L16)  src/lib.rs(L18 - L23) 

Construction and Conversion Methods

The CpuMask type provides multiple ways to create and convert between different representations.

Basic Construction

Advanced Construction

Conversion Methods

Sources: src/lib.rs(L72 - L146) 

Query and Inspection Operations

flowchart TD
subgraph subGraph2["Index Finding (False Bits)"]
    I["first_false_index()"]
    I1["Option<usize>"]
    J["last_false_index()"]
    J1["Option<usize>"]
    K["next_false_index(idx)"]
    K1["Option<usize>"]
    E["first_index()"]
    E1["Option<usize>"]
    F["last_index()"]
    F1["Option<usize>"]
    G["next_index(idx)"]
    G1["Option<usize>"]
    H["prev_index(idx)"]
    H1["Option<usize>"]
    A["get(index)"]
    A1["Returns bool"]
    B["len()"]
    B1["Count of set bits"]
    C["is_empty()"]
    C1["No bits set"]
    D["is_full()"]
    D1["All bits set"]
    subgraph subGraph1["Index Finding (True Bits)"]
        L["prev_false_index(idx)"]
        L1["Option<usize>"]
        subgraph subGraph0["Bit Query Operations"]
            I["first_false_index()"]
            I1["Option<usize>"]
            J["last_false_index()"]
            J1["Option<usize>"]
            K["next_false_index(idx)"]
            K1["Option<usize>"]
            E["first_index()"]
            E1["Option<usize>"]
            F["last_index()"]
            F1["Option<usize>"]
            G["next_index(idx)"]
            G1["Option<usize>"]
            H["prev_index(idx)"]
            H1["Option<usize>"]
            A["get(index)"]
            A1["Returns bool"]
            B["len()"]
            B1["Count of set bits"]
            C["is_empty()"]
            C1["No bits set"]
            D["is_full()"]
            D1["All bits set"]
        end
    end
end

A --> A1
B --> B1
C --> C1
D --> D1
E --> E1
F --> F1
G --> G1
H --> H1
I --> I1
J --> J1
K --> K1
L --> L1

Bit Testing Operations

Index Finding Operations

Sources: src/lib.rs(L148 - L228) 

Modification and Iteration

Modification Operations

Iterator Interface

The CpuMask implements IntoIterator for &CpuMask<SIZE>, yielding indices of set bits.

flowchart TD
subgraph subGraph1["Iter Struct Fields"]
    J["head: Option<usize>"]
    K["tail: Option<usize>"]
    L["data: &'a CpuMask<SIZE>"]
end
subgraph subGraph0["Iterator Implementation"]
    A["&CpuMask<SIZE>"]
    B["IntoIterator"]
    C["Iter<'a, SIZE>"]
    D["Iterator"]
    E["DoubleEndedIterator"]
    F["next()"]
    G["Option<usize>"]
    H["next_back()"]
    I["Option<usize>"]
end

A --> B
B --> C
C --> D
C --> E
C --> J
C --> K
C --> L
D --> F
E --> H
F --> G
H --> I

Sources: src/lib.rs(L172 - L180)  src/lib.rs(L230 - L234)  src/lib.rs(L237 - L251)  src/lib.rs(L412 - L518) 

Bitwise Operations and Trait Implementations

Binary Bitwise Operations

flowchart TD
subgraph subGraph0["Binary Operations"]
    E["&="]
    E1["BitAndAssign"]
    D["!CpuMask"]
    D1["Not - Complement"]
    A["CpuMask & CpuMask"]
    A1["BitAnd - Intersection"]
    C["CpuMask ^ CpuMask"]
    C1["BitXor - Symmetric Difference"]
    subgraph subGraph2["Assignment Operations"]
        F["|="]
        F1["BitOrAssign"]
        G["^="]
        G1["BitXorAssign"]
        B["CpuMask | CpuMask"]
        B1["BitOr - Union"]
        subgraph subGraph1["Unary Operations"]
            E["&="]
            E1["BitAndAssign"]
            D["!CpuMask"]
            D1["Not - Complement"]
            A["CpuMask & CpuMask"]
            A1["BitAnd - Intersection"]
        end
    end
end

A --> A1
B --> B1
C --> C1
D --> D1
E --> E1
F --> F1
G --> G1

Standard Trait Implementations

Sources: src/lib.rs(L17)  src/lib.rs(L25 - L66)  src/lib.rs(L253 - L326) 

Array Conversion Implementations

For large CPU counts, the library provides From trait implementations for array conversions:

These implementations enable direct conversion between CpuMask instances and their underlying array storage for sizes exceeding 128 bits.

Sources: src/lib.rs(L328 - L410)