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
• Usage
• Design Philosophy
• Tech Stack
• Directory Structure
• API Reference
• History: The Quest for Speed

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

• Language: Rust
• Core Dependency: coarsetime
• Repository: https://github.com/js0-site/rust.git
• License: MulanPSL-2.0

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:

• Google Group
• js0site.bsky.social

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

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

目录

• 功能特性
• 使用演示
• 设计思路
• 技术堆栈
• 目录结构
• 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），用户可以按需编译所需功能。

技术堆栈

• 编程语言: Rust
• 核心依赖: coarsetime
• 代码仓库: https://github.com/js0-site/rust.git
• 许可证: MulanPSL-2.0

目录结构

.
├── 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 ⋅ 重构互联网计划 的开源组件。

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

• 谷歌邮件列表
• js0site.bsky.social