ts_ 0.1.4

[English](#en) | [中文](#zh)

---

<a id="en"></a>
# ts\_ : High-performance, lightweight time measurement for Rust

- [ts\_ : High-performance, lightweight time measurement for Rust](#ts_-high-performance-lightweight-time-measurement-for-rust)
  - [Table of Contents](#table-of-contents)
  - [Features](#features)
  - [Usage](#usage)
    - [Example](#example)
  - [Design Philosophy](#design-philosophy)
  - [Tech Stack](#tech-stack)
  - [Directory Structure](#directory-structure)
  - [API Reference](#api-reference)
    - [`nano()`](#nano)
    - [`milli()`](#milli)
    - [`sec()`](#sec)
  - [History: The Quest for Speed](#history-the-quest-for-speed)
  - [About](#about)

`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](#features)
- [Usage](#usage)
- [Design Philosophy](#design-philosophy)
- [Tech Stack](#tech-stack)
- [Directory Structure](#directory-structure)
- [API Reference](#api-reference)
- [History: The Quest for Speed](#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`:

```toml
[dependencies]
ts_ = "0.1.2"
```

Enable the features you need:

```toml
[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:

```rust
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()`

```rust
pub fn nano() -> u64
```

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

### `milli()`

```rust
pub fn milli() -> u64
```

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

### `sec()`

```rust
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 library is developed by [WebC.site](https://webc.site).

[WebC.site](https://webc.site): A new paradigm of web development for AI


---

<a id="zh"></a>
# ts\_ : Rust 高性能轻量级时间测量库

- [ts\_ : Rust 高性能轻量级时间测量库](#ts_-rust-高性能轻量级时间测量库)
  - [目录](#目录)
  - [功能特性](#功能特性)
  - [使用演示](#使用演示)
    - [示例代码](#示例代码)
  - [设计思路](#设计思路)
  - [技术堆栈](#技术堆栈)
  - [目录结构](#目录结构)
  - [API 参考](#api-参考)
    - [`nano()`](#nano)
    - [`milli()`](#milli)
    - [`sec()`](#sec)
  - [历史趣闻：对速度的极致追求](#历史趣闻对速度的极致追求)
  - [关于](#关于)

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

## 目录

- [功能特性](#功能特性)
- [使用演示](#使用演示)
- [设计思路](#设计思路)
- [技术堆栈](#技术堆栈)
- [目录结构](#目录结构)
- [API 参考](#api-参考)
- [历史趣闻](#历史趣闻)

## 功能特性

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

## 使用演示

在 `Cargo.toml` 中添加 `ts_`：

```toml
[dependencies]
ts_ = "0.1.2"
```

按需启用特性：

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

### 示例代码

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

```rust
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()`

```rust
pub fn nano() -> u64
```

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

### `milli()`

```rust
pub fn milli() -> u64
```

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

### `sec()`

```rust
pub fn sec() -> u64
```

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

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

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

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

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


## 关于

本库由 [WebC.site](https://webc.site) 开发。

[WebC.site](https://webc.site) : 面向人工智能的网站开发新范式