Skip to content

api_common.md

Latest commit

 

History

History
102 lines (81 loc) · 2.98 KB

api_common.md

File metadata and controls

102 lines (81 loc) · 2.98 KB
Raw

API: Common Module (Canonical)

Status: Shared

Purpose

Canonical reference for the src/common module, which provides shared input types, hashing utilities, data structures, and heavy-hitter helpers used across sketches and frameworks.

Module Organization

File: src/common/mod.rs

src/common/
├── mod.rs                  # Public exports
├── input.rs                # DataInput/HeapItem/HHItem + Hydra enums
├── hash.rs                 # Hash traits, constants, and matrix hash helpers
├── heap.rs                 # HHHeap
├── structure_utils.rs      # Nitro and median utility
├── precompute_hash.rs      # PRECOMPUTED_HASH
├── precompute_sample.rs    # PRECOMPUTED_SAMPLE
├── precompute_sample2.rs   # PRECOMPUTED_SAMPLE_RATE_1PERCENT
└── structures/
    ├── vector1d.rs
    ├── vector2d.rs
    ├── vector3d.rs
    ├── matrix_storage.rs
    ├── fixed_structure.rs
    └── heap.rs

Public Exports

use asap_sketchlib::common::{
    // Input layer
    DataInput, HeapItem, HHItem, L2HH,
    input_to_owned, heap_item_to_sketch_input,

    // Hash layer
    SketchHasher, DefaultXxHasher,
    SEEDLIST, CANONICAL_HASH_SEED, BOTTOM_LAYER_FINDER, HYDRA_SEED,
    MatrixHashMode,
    hash64_seeded, hash128_seeded,
    hash_item64_seeded, hash_item128_seeded,
    hash_mode_for_matrix,
    hash_for_matrix, hash_for_matrix_seeded,
    hash_for_matrix_seeded_with_mode,
    hash_for_matrix_seeded_with_mode_generic,
    hash_for_matrix_generic, hash_for_matrix_seeded_generic,

    // Structure layer
    MatrixStorage, FastPathHasher, MatrixHashType,
    Vector1D, Vector2D, Vector3D,
    FixedMatrix, HllBucketList,
    DefaultMatrixI32, DefaultMatrixI64, DefaultMatrixI128,
    QuickMatrixI32, QuickMatrixI64, QuickMatrixI128,
    CommonHeap, CommonHeapOrder, KeepSmallest, KeepLargest,

    // HH helper + utilities
    HHHeap,
    Nitro, compute_median_inline_f64,

    // Precomputed assets
    PRECOMPUTED_HASH,
    PRECOMPUTED_SAMPLE,
    PRECOMPUTED_SAMPLE_RATE_1PERCENT,
};

Canonical Subpages

Cross-Cutting Notes

  • DataInput/HeapItem define borrowed-vs-owned key semantics used across all sketches and heaps.
  • SketchHasher enables custom hash injection for sketches that support hasher generics.
  • Matrix fast paths choose hash packing mode automatically through hash_mode_for_matrix(rows, cols).
  • HHHeap is built for top-k heavy hitter maintenance and key lookup.

Quick Example

use asap_sketchlib::{hash64_seeded, DataInput, Vector2D, CANONICAL_HASH_SEED};

let _h = hash64_seeded(CANONICAL_HASH_SEED, &DataInput::U64(42));
let matrix = Vector2D::<i32>::init(3, 16);
assert_eq!(matrix.rows(), 3);

Status

Primary common-module entry point.