noxu_xa/lib.rs
1// Copyright (C) 2024-2025 Greg Burd. Licensed under either of the
2// Apache License, Version 2.0 or the MIT license, at your option.
3// See LICENSE-APACHE and LICENSE-MIT at the root of this repository.
4// SPDX-License-Identifier: Apache-2.0 OR MIT
5
6//! > **Internal component of the [`noxu`](https://crates.io/crates/noxu) database.**
7//! >
8//! > This crate is published only so the `noxu` umbrella crate can depend on it.
9//! > Use `noxu` (`noxu = "3"`) in applications; depend on this crate directly only
10//! > if you are extending the engine internals. Its API may change without a major
11//! > version bump.
12//!
13//! XA distributed transaction support for Noxu DB.
14//!
15//! This crate implements the X/Open XA interface for coordinating distributed
16//! transactions across multiple Noxu environments. It provides:
17//!
18//! - `Xid` — XA transaction identifier (format_id + global_transaction_id + branch_qualifier)
19//! - `XaFlags` — flags for XA operations (JOIN, RESUME, TMSUCCESS, ONEPHASE, etc.)
20//! - `XaResource` — trait defining the XA resource manager interface
21//! - `XaEnvironment` — implementation of `XaResource` backed by a Noxu Environment
22//!
23//! # Example
24//!
25//! ```ignore
26//! use noxu_xa::{XaEnvironment, XaResource, Xid, XaFlags, PrepareResult};
27//!
28//! let xa = XaEnvironment::new(env);
29//! let xid = Xid::new(1, b"global_txn_1", b"branch_1").unwrap();
30//!
31//! xa.xa_start(&xid, XaFlags::NOFLAGS)?;
32//! // ... perform database operations using xa.get_transaction(&xid) ...
33//! xa.xa_end(&xid, XaFlags::TMSUCCESS)?;
34//!
35//! match xa.xa_prepare(&xid, XaFlags::NOFLAGS)? {
36//! PrepareResult::Ok => xa.xa_commit(&xid, XaFlags::NOFLAGS)?,
37//! PrepareResult::ReadOnly => {} // no commit needed
38//! }
39//! ```
40
41// noxu-xa contains no `unsafe` (the former transaction-pointer dereference in
42// `environment.rs` was replaced by an `Arc<Transaction>` handle in the v3.x
43// soundness pass). Forbid it to keep the crate safe.
44#![forbid(unsafe_code)]
45
46pub mod environment;
47pub mod error;
48pub mod flags;
49pub mod prepared_log;
50pub mod resource;
51pub mod xid;
52
53pub use environment::XaEnvironment;
54pub use error::{PrepareResult, XaError, XaResult};
55pub use flags::XaFlags;
56pub use prepared_log::PreparedLog;
57pub use resource::XaResource;
58pub use xid::{Xid, XidError};