Module pagination 

Generic two-level locking TTL-based pagination cache.

This module provides a thread-safe pagination cache that can be used by MCP servers to implement implicit pagination - where repeated calls with the same parameters automatically advance through pages.

Architecture

Uses two-level locking for thread safety:

• Level 1: Brief lock on outer HashMap to get/create per-query state
• Level 2: Per-query lock held during work, serializing same-param calls

Example

use agentic_tools_utils::pagination::{PaginationCache, paginate_slice};

// Create a cache for your result type
let cache: PaginationCache<i32> = PaginationCache::new();

// Get or create a lock for a query
let lock = cache.get_or_create("my-query-key");

// Work with the query state
{
    let mut state = lock.state.lock().unwrap();
    if state.is_empty() {
        // Fetch results and populate state
        state.reset(vec![1, 2, 3, 4, 5], (), 2);
    }
}

Structs

PaginationCache

Two-level locking pagination cache generic over result T and optional meta M.

QueryLock

Per-query lock protecting the query state.

QueryState

State for a cached query including full results and pagination offset.

Constants

DEFAULT_TTL

Default TTL for pagination state: 5 minutes.

Functions

paginate_slice

Paginate a slice without consuming it.