TxMap

A concurrent transactional hash map for Rust with fine-grained user-defined locking, internal mutability for easy sharing, and composable transactions.

Features

• Flexible sharding Choose the number of shards (between 8 and 128). Decide how they're locked (Mutex, RwLock or bring your own)
• Transactions Atomic, composable batches of modifications
• Guards/conditions Declarative preconditions that must hold before a transaction runs
• Parameterized transactions Optionally define a parameter type to pass into transaction closures
• Builder API Chain operations to build transactions with a fluent interface

License

Licensed under the MIT License.

Usage

Add txmap to your Cargo.toml:

[dependencies]
txmap = "1.1.0"

Creating a TxMap

use txmap::prelude::*;

// Shard counts available are [8, 16, 32, 64, 128]
let map: TxMap<String, u64> = TxMap::new(ShardCount::_8);

Lock Policy

The lock policy can be set using the with_lock_policy constructor. Two policies are provided: MutexLockPolicy and RwLockPolicy. The default is MutexLockPolicy. You can also implement your own policy by implementing LockPolicy.

// Creating a TxMap with a lock policy
let map = TxMap::with_lock_policy::<MyLockPolicy>(ShardCount::_8);

Key type requirements

The key type K must implement Hash and Eq. Some functions require Clone.

The value type V has no trait bounds by default. Functions that create default values (e.g., insert_default) require V: Default.

Transactions

Transactions group multiple operations into an atomic unit. They are built using a fluent builder API. Use .into_transaction() to produce a reusable transaction, then .execute() to run it. They can be run as many times as you want within the lifetime of the TxMap it was created from.

Simple transaction

use txmap::prelude::*;

let db: TxMap<String, u64> = TxMap::new(ShardCount::_8);

db.insert("alice".into(), 100);
db.insert("bob".into(), 0);

// Transfer 50 from alice to bob in one atomic transaction
let result = db.transaction()
    .modify("alice".into(), |_name, balance| {
        *balance -= 50;
    })
    .modify("bob".into(), |_name, balance| {
        *balance += 50;
    })
    .get_copied(vec!["alice".into(), "bob".into()])
    .into_transaction()
    .execute();

match result {
    // every .execute() call return a TxResult
    case TxResult::Completed(balances) => {
        assert_eq!(balances, vec![Some(50), Some(50)]);
    },
    _ => {}
}

Transaction with guards (preconditions)

Perhaps Alice doesn't have enough funds to make a transfer and you need to prevent a transfer happening. Guards can be used to veto a transaction if they fail, in which case TxResult::RequirementNotMet is returned.

use txmap::prelude::*;

let db: TxMap<String, u64> = TxMap::new(ShardCount::_8);
db.insert("alice".into(), 100);
db.insert("bob".into(), 0);

let result = db
    .transaction()
    // Add all your requirements up front
    // Requirements cannot be added after modifications
    .require(
        "Alice has sufficient funds",
        ["alice".into()],
        |[balance]| balance.is_some_and(|b| *b >= 250),
    )
    .require(
        "Bob has an account",
        ["bob".into()],
        |[balance]| balance.is_some(),
    )
    .modify("alice".into(), |_name, balance| {
        *balance -= 250;
    })
    .modify("bob".into(), |_name, balance| {
        *balance += 250;
    })
    .get_copied(vec!["alice".into(), "bob".into()])
    .into_transaction()
    .execute();

match result {
    case TxResult::RequirementNotMet(guard_idx, guard_name) => {
        assert_eq!(guard_idx, 0);
        assert_eq!(guard_name, "Alice has sufficient funds");
    },
    _ => {}
}

Transaction returning a value

As seen already, a completed transaction can optionally return a final value in the result. There are 6 functions like this that can be used

Parameterized transactions

A transaction may need to be called with different parameters.

The function with_param::<MyParams>() lets you do this by parameterizing the transaction.

use txmap::prelude::*;

#[derive(Default)]
struct Transfer {
    amount: u64,
}

let db: TxMap<String, u64> = TxMap::new(ShardCount::_8);
db.insert("alice".into(), 200);
db.insert("bob".into(), 0);

let transfer = db
    .transaction()
    // Parameter type is set before requirements
    .with_param::<Transfer>()
    .require(
        "Alice has sufficient funds",
        ["alice".into()],
        |[balance], params| balance.is_some_and(|b| *b >= params.amount),
    )
    .modify("alice".into(), |_name, balance, params| {
        *balance -= params.amount;
    })
    .modify("bob".into(), |_name, balance, params| {
        *balance += params.amount;
    })
    .get_all_copied(["alice".into(), "bob".into()])
    .into_transaction();

// Execute with different parameters
let result1 = transfer.execute(&Transfer { amount: 50 });
assert_eq!(result1, TxResult::Completed(vec![Some(150), Some(50)]));

let result2 = transfer.execute(&Transfer { amount: 30 });
assert_eq!(result2, TxResult::Completed(vec![Some(120), Some(80)]));

Transaction operations

Transactions are built with a fluent interface, many operations can be chained together atomically into a single transaction. Available transaction operations are as follows

TxMap operations

All transaction operations are also available on TxMap. In addition there are some operations that require locking the entire map which are only available on TxMap. These are as follows