rustfs/crates/config/src/constants/zero_copy.rs

// Copyright 2024 RustFS Team
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! Mmap-based read I/O configuration constants.
//!
//! This module defines environment variables and default values for mmap-based
//! read operations. Note: the legacy "zero_copy" env var is kept as a
//! deprecated compatibility alias; the actual implementation performs
//! mmap-then-copy, not true zero-copy.

// =============================================================================
// Mmap Read Configuration
// =============================================================================

/// Environment variable for mmap-based read enable.
///
/// When enabled, uses mmap (Unix) or optimized reads for file access.
/// This reduces memory copies from 3-4 to 1, lowering CPU usage and
/// improving latency for large object reads.
///
/// - Purpose: Enable or disable mmap-based read operations
/// - Acceptable values: `"true"` / `"false"` (case-insensitive) or a boolean typed config
/// - Semantics: When enabled, uses mmap on Unix systems for memory-mapped file reads;
///   falls back to regular I/O on non-Unix platforms or when mmap fails
/// - Example: `export RUSTFS_OBJECT_MMAP_READ_ENABLE=true`
pub const ENV_OBJECT_MMAP_READ_ENABLE: &str = "RUSTFS_OBJECT_MMAP_READ_ENABLE";

/// Deprecated compatibility alias for mmap-based read enable.
///
/// Prefer [`ENV_OBJECT_MMAP_READ_ENABLE`]. When both variables are set, the
/// canonical mmap-read variable takes precedence.
pub const ENV_OBJECT_ZERO_COPY_ENABLE: &str = "RUSTFS_OBJECT_ZERO_COPY_ENABLE";

/// Default: mmap-based reads are enabled.
///
/// Uses memory mapping (mmap) on Unix systems, then copies data into owned
/// Bytes. This is faster than multiple read+copy passes but is NOT true
/// zero-copy (the data is still copied once from the mmap region).
///
/// On non-Unix platforms or when mmap fails, the system automatically falls back
/// to regular I/O without errors.
pub const DEFAULT_OBJECT_MMAP_READ_ENABLE: bool = true;

/// Deprecated compatibility alias for mmap-based read default.
///
/// Prefer [`DEFAULT_OBJECT_MMAP_READ_ENABLE`].
pub const DEFAULT_OBJECT_ZERO_COPY_ENABLE: bool = DEFAULT_OBJECT_MMAP_READ_ENABLE;

// =============================================================================
// Direct I/O Configuration
// =============================================================================

/// Environment variable for Direct I/O enable (Linux only).
///
/// When enabled, uses O_DIRECT flag to bypass OS page cache for large files.
/// This is only beneficial for specific workloads (databases, large sequential reads).
///
/// - Purpose: Enable or disable Direct I/O for large file operations
/// - Acceptable values: `"true"` / `"false"` (case-insensitive) or a boolean typed config
/// - Semantics: When enabled, files larger than the threshold will use O_DIRECT flag;
///   this bypasses the OS page cache and transfers data directly between disk and application
/// - Example: `export RUSTFS_OBJECT_DIRECT_IO_ENABLE=true`
/// - Note: Direct I/O is disabled by default because it's only beneficial for specific
///   use cases. For most workloads, the OS page cache provides better performance.
pub const ENV_OBJECT_DIRECT_IO_ENABLE: &str = "RUSTFS_OBJECT_DIRECT_IO_ENABLE";

/// Default: Direct I/O is disabled.
///
/// Direct I/O is disabled by default because it's only beneficial for specific use cases:
/// - Large file transfers (>128MB)
/// - Databases with their own cache
/// - Applications requiring predictable I/O latency
///
/// For most workloads, the OS page cache provides better performance through:
/// - Read-ahead caching
/// - Write buffering
/// - Multi-use caching (same data cached for multiple operations)
pub const DEFAULT_OBJECT_DIRECT_IO_ENABLE: bool = false;

/// Environment variable for Direct I/O minimum file size threshold.
///
/// Files smaller than this size will use regular I/O even if Direct I/O is enabled.
/// This avoids the overhead of Direct I/O for small files where the OS page cache
/// is more effective.
///
/// - Purpose: Set the minimum file size for Direct I/O operations
/// - Unit: Bytes
/// - Valid values: any positive integer (default: 134,217,728 bytes = 128 MB)
/// - Semantics: Only files larger than this threshold will use Direct I/O when enabled;
///   smaller files use regular buffered I/O
/// - Example: `export RUSTFS_OBJECT_DIRECT_IO_THRESHOLD=268435456`
/// - Note: The default threshold of 128MB balances the overhead of Direct I/O setup
///   against the benefits of bypassing the page cache for large files.
pub const ENV_OBJECT_DIRECT_IO_THRESHOLD: &str = "RUSTFS_OBJECT_DIRECT_IO_THRESHOLD";

/// Default Direct I/O threshold: 128 MB.
///
/// Only files larger than 128MB will use Direct I/O when enabled.
/// Smaller files benefit from OS page cache.
///
/// Formula: 128 * 1024 * 1024 = 134,217,728 bytes
pub const DEFAULT_OBJECT_DIRECT_IO_THRESHOLD: usize = 128 * 1024 * 1024;