Crate apr 

Safe Rust bindings for the Apache Portable Runtime (APR) library.

This crate provides safe Rust abstractions over the Apache Portable Runtime (APR) and APR-Util C libraries. APR is a portability layer that provides a predictable and consistent interface to underlying platform-specific implementations.

Primary Use Case

This crate is primarily useful when developing Rust bindings for C libraries that depend on APR. Many Apache projects and other C libraries use APR for cross-platform compatibility and memory management. If you’re creating Rust bindings for such libraries, this crate provides the necessary APR functionality with a safe Rust interface.

Core Concepts

Memory Pools

APR uses a hierarchical memory pool system for all memory allocation. This is fundamental to how APR and APR-based libraries work:

use apr::Pool;

// Create a root pool
let pool = Pool::new();

// Create a subpool for scoped allocations
let subpool = pool.create_subpool().unwrap();
// Memory in subpool is freed when subpool is dropped

Error Handling

APR functions return status codes that this crate converts to Rust Result types:

use apr::{Pool, file::File};

let pool = Pool::new();
match File::open("example.txt", apr::file::Flag::READ, 0, &pool) {
    Ok(file) => { /* use file */ },
    Err(e) => eprintln!("Failed to open file: {}", e),
}

Interfacing with C Libraries

When working with C libraries that use APR, you’ll often need to pass raw APR pointers:

use apr::{Pool, Status};

extern "C" {
    fn some_apr_function(pool: *mut apr_sys::apr_pool_t) -> apr_sys::apr_status_t;
}

let pool = Pool::new();
let status = unsafe {
    Status::from(some_apr_function(pool.as_mut_ptr()))
};

Module Overview

• pool - Memory pool management (fundamental to APR)
• error - Error types and status code handling
• [file] - File I/O operations
• network - Network I/O and socket operations
• hash - Hash table implementation
• tables - Ordered key-value pairs
• strings - String manipulation utilities
• time - Time handling and formatting
• crypto - Cryptographic functions (MD5, SHA1)
• base64 - Base64 encoding/decoding
• uri - URI parsing and manipulation
• uuid - UUID generation
• xml - XML parsing utilities

Safety

This crate aims to provide safe abstractions, but when interfacing with C:

• Some operations require unsafe blocks for raw pointer handling
• APR initialization is handled automatically via Rust’s runtime
• Memory pools ensure proper cleanup when dropped
• The crate leverages Rust’s ownership system for resource management

Re-exports

pub use error::Error;

pub use error::ErrorContext;

pub use error::Result;

pub use pool::Pool;

pub use pool::PoolHandle;

pub use pool::SharedPool;

pub use status::Status;

Modules

base64

Base64 encoding and decoding Base64 encoding and decoding functionality from apr-util.

callbacks

Callback function types and utilities Callback support infrastructure for C callbacks with Rust closures.

crypto

Cryptographic operations (encryption, decryption) Cryptographic functionality from apr-util.

date

Date parsing and formatting utilities Date parsing functions

error

Error types and result handling Improved error handling for APR operations

file

File I/O operations File handling

getopt

Command-line option parsing Command line option parsing.

hash

Hash table data structure Hash table support.

md5

MD5 hashing functions MD5 hashing functionality from apr-util.

mmap

Memory-mapped file support Memory-mapped file operations

network

Network I/O and socket operations Network I/O with safe socket wrappers

paths

File path manipulation utilities Path handling utilities for cross-platform operations.

pool

Memory pool management Memory pool management.

queue

Thread-safe queue data structure Thread-safe FIFO queue implementation.

sha1

SHA1 hashing functions SHA1 hashing functionality from apr-util.

status

APR status codes Status codes and error handling.

strings

String manipulation utilities String utilities for safe C string handling.

strmatch

String pattern matching String matching functionality from apr-util.

tables

APR table data structure (ordered key-value pairs) APR tables and arrays implementation.

time

Time handling and conversion Time handling.

uri

URI parsing and manipulation URI parsing and manipulation.

uuid

UUID generation UUID generation functionality from apr-util.

versions

Version information Version information for the Apache Portable Runtime (APR) and Apache Portable Utility (APU) libraries.

xlate

Character set translation Character set translation functionality from apr-util.

xml

XML parsing utilities XML parsing functionality from apr-util.

Macros

apr_array

Create an APR array with initial values.

apr_hash

Create an APR hash with initial key-value pairs.

apr_table

Create an APR table with initial key-value pairs.

Functions

initialize^⚠

Initialize the APR library.

terminate^⚠

Terminate the APR library and clean up all internal data structures.

Type Aliases

apr_status_t

Type for specifying an error or status code.

apr_time_t

number of microseconds since 00:00:00 January 1, 1970 UTC