ts_ 0.1.3

High-performance, lightweight time measurement library based on coarsetime. / 基于 coarsetime 的高性能轻量级时间测量库。
Documentation

English | 中文

ts_ : High-performance, lightweight time measurement for Rust

ts_ is a simplified wrapper around the coarsetime crate, designed to provide extremely fast and easy-to-use time measurement utilities. It focuses on speed and API stability, making it ideal for performance-critical applications where high-precision (but not necessarily atomic-clock level) timestamps are needed without the overhead of standard library calls.

Table of Contents

Features

  • High Performance: Leverages CLOCK_MONOTONIC_COARSE on Linux systems for minimal overhead.
  • Simplicity: Exposes a straightforward API with nano(), milli(), and sec() functions.
  • Stability: Consistent behavior across different platforms, avoiding runtime panics common in some standard library implementations.
  • Lightweight: Minimal dependencies and optimized for speed.
  • Flexible Precision: Choose between nanoseconds, milliseconds, or seconds based on your needs.

Usage

Add ts_ to your Cargo.toml:

[dependencies]
ts_ = "0.1.2"

Enable the features you need:

[dependencies]
ts_ = { version = "0.1.2", features = ["nano", "milli", "sec"] }

Example

Here is a simple example demonstrating how to retrieve the current time in different precisions:

use aok::{OK, Void};
use log::info;

#[test]
fn test() -> Void {
  // Get current time in nanoseconds (requires "nano" feature)
  info!("{}", ts_::nano());

  // Get current time in milliseconds (requires "milli" feature)
  info!("{}", ts_::milli());

  // Get current time in seconds (requires "sec" feature)
  info!("{}", ts_::sec());

  OK
}

Design Philosophy

The core design philosophy of ts_ is "Speed over Accuracy".

  1. Underlying Mechanism: It wraps coarsetime, which uses CLOCK_MONOTONIC_COARSE on Linux. This avoids expensive system calls by reading the time directly from a memory page updated by the kernel (vDSO).
  2. Simplified API: Instead of dealing with complex Duration or Instant objects for simple timestamp needs, ts_ provides direct access to u64 values representing time.
  3. Feature Flags: Users can opt-in for nano or sec precision features to keep the compilation minimal.

Tech Stack

Directory Structure

.
├── src/
│   └── lib.rs      # Core implementation exporting nano() and sec()
├── tests/
│   └── main.rs     # Integration tests and usage examples
├── Cargo.toml      # Project configuration
└── readme/         # Documentation

API Reference

nano()

pub fn nano() -> u64

Returns the current time in nanoseconds since the epoch. Requires the nano feature.

milli()

pub fn milli() -> u64

Returns the current time in milliseconds since the epoch. Requires the milli feature.

sec()

pub fn sec() -> u64

Returns the current time in seconds since the epoch. Requires the sec feature.

History: The Quest for Speed

In the early days of Linux, getting the time was always a system call. A system call involves switching from user mode to kernel mode, which is a relatively expensive operation for the CPU. For high-performance applications that needed to check the time thousands or millions of times per second (like high-frequency trading or high-throughput servers), this overhead was significant.

To solve this, the Linux kernel introduced the vDSO (Virtual Dynamic Shared Object) mechanism. This allows the kernel to map a small area of memory into the user space of every process. This memory contains frequently used data, such as the current time.

CLOCK_MONOTONIC_COARSE was born from this innovation. It reads the time directly from this shared memory without triggering a context switch. While it might be slightly less precise than a full system call (updating only on timer ticks), it is orders of magnitude faster. ts_ (via coarsetime) harnesses this power to give your Rust applications blazing fast time measurements.

About

This project is an open-source component of js0.site ⋅ Refactoring the Internet Plan.

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

ts_ : Rust 高性能轻量级时间测量库

ts_ 是 coarsetime crate 的简化封装，旨在提供极速且易用的时间测量工具。它专注于速度和 API 稳定性，非常适合那些需要高性能时间戳但不需要原子钟级精度的应用场景，避免了标准库调用的额外开销。

目录

功能特性

  • 高性能：在 Linux 系统上利用 CLOCK_MONOTONIC_COARSE，将开销降至最低。
  • 极简易用：暴露 nano()、milli() 和 sec() 三个核心函数，上手即用。
  • 跨平台稳定：在不同平台上保持一致的行为，避免了标准库在某些平台上可能出现的运行时 panic。
  • 轻量级：依赖极少，专为速度优化。
  • 灵活精度：根据需求选择纳秒、毫秒或秒级精度。

使用演示

在 Cargo.toml 中添加 ts_：

[dependencies]
ts_ = "0.1.2"

按需启用特性：

[dependencies]
ts_ = { version = "0.1.2", features = ["nano", "milli", "sec"] }

示例代码

以下代码展示了如何获取不同精度的时间戳：

use aok::{OK, Void};
use log::info;

#[test]
fn test() -> Void {
  // 获取当前纳秒时间戳（需要 "nano" 特性）
  info!("{}", ts_::nano());

  // 获取当前毫秒时间戳（需要 "milli" 特性）
  info!("{}", ts_::milli());

  // 获取当前秒级时间戳（需要 "sec" 特性）
  info!("{}", ts_::sec());

  OK
}

设计思路

ts_ 的核心设计理念是 “速度优先”。

  1. 底层机制：封装了 coarsetime，在 Linux 上使用 CLOCK_MONOTONIC_COARSE。通过读取内核更新的内存页（vDSO）直接获取时间，避免了昂贵的系统调用。
  2. 简化 API：摒弃了复杂的 Duration 或 Instant 对象，直接提供 u64 类型的时间数值，满足最纯粹的时间获取需求。
  3. 按需加载：通过 nano 和 sec 特性标志（Feature Flags），用户可以按需编译所需功能。

技术堆栈

目录结构

.
├── src/
│   └── lib.rs      # 核心实现，导出 nano() 和 sec()
├── tests/
│   └── main.rs     # 集成测试与使用示例
├── Cargo.toml      # 项目配置
└── readme/         # 文档目录

API 参考

nano()

pub fn nano() -> u64

返回自纪元以来的当前时间（纳秒）。需要启用 nano 特性。

milli()

pub fn milli() -> u64

返回自纪元以来的当前时间（毫秒）。需要启用 milli 特性。

sec()

pub fn sec() -> u64

返回自纪元以来的当前时间（秒）。需要启用 sec 特性。

历史趣闻：对速度的极致追求

在 Linux 的早期，获取时间总是一次系统调用（System Call）。系统调用意味着 CPU 需要从用户态切换到内核态，这对于处理器来说是一个相对昂贵的操作。对于那些需要每秒成千上万次检查时间的高性能应用（如高频交易或高吞吐量服务器）来说，这种开销是不可忽视的。

为了解决这个问题，Linux 内核引入了 vDSO (Virtual Dynamic Shared Object) 机制。它允许内核将一小块内存映射到每个进程的用户空间。这块内存包含了经常使用的数据，比如当前时间。

CLOCK_MONOTONIC_COARSE 正是这一创新的产物。它直接从这块共享内存中读取时间，而无需触发上下文切换。虽然它的精度可能略低于完整的系统调用（仅在定时器滴答时更新），但它的速度却快了几个数量级。ts_（通过 coarsetime）正是利用了这一机制，为您的 Rust 应用提供闪电般的时间测量能力。

关于

本项目为 js0.site ⋅ 重构互联网计划 的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：