{"id":49873819,"url":"https://github.com/marsxuefeng/atoma","last_synced_at":"2026-05-15T11:35:38.052Z","repository":{"id":322921349,"uuid":"1017912761","full_name":"marsxuefeng/atoma","owner":"marsxuefeng","description":"Atoma: Distributed Concurrency Primitives for MongoDB","archived":false,"fork":false,"pushed_at":"2026-02-04T14:19:08.000Z","size":1607,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-05T01:35:07.447Z","etag":null,"topics":["barrier","countdownlatch","doublebarrier","mongo","mutexlock","readwritelock","semphore"],"latest_commit_sha":null,"homepage":"https://deepwiki.com/Maple-mxf/atoma","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marsxuefeng.png","metadata":{"files":{"readme":"README_zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-11T09:45:11.000Z","updated_at":"2026-02-04T14:23:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marsxuefeng/atoma","commit_stats":null,"previous_names":["maple-mxf/atoma","marsxuefeng/atoma"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/marsxuefeng/atoma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marsxuefeng%2Fatoma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marsxuefeng%2Fatoma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marsxuefeng%2Fatoma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marsxuefeng%2Fatoma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marsxuefeng","download_url":"https://codeload.github.com/marsxuefeng/atoma/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marsxuefeng%2Fatoma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33065648,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["barrier","countdownlatch","doublebarrier","mongo","mutexlock","readwritelock","semphore"],"created_at":"2026-05-15T11:35:37.351Z","updated_at":"2026-05-15T11:35:38.048Z","avatar_url":"https://github.com/marsxuefeng.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Atoma: 分布式协调原子原语库\n\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/atoma-project/atoma-java)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Maven Central](https://img.shields.io/maven-central/v/io.atoma/atoma-api.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:io.atoma)\n\n**Atoma** 是一个使用 Java 实现的、轻量级且高性能的分布式协调原语库。它旨在将传统并发编程中广为人知的同步工具（如 `Lock`, `Semaphore`, `CountDownLatch`）引入到分布式环境中，从而帮助开发者简单、可靠地构建分布式系统。\n\n## 简介\n\n在复杂的分布式系统中，跨多台机器的协调与同步是一个普遍存在的难题。Atoma 提供了一套与 `java.util.concurrent` 包类似但专为分布式环境设计的 API，使得开发者可以用熟悉的方式解决分布式场景下的资源竞争、任务同步和流程控制等问题。\n\n项目的设计哲学是**API 优先**和**可插拔后端**。核心 API (`atoma-api`) 与具体的存储实现解耦，目前官方提供了一个基于 **MongoDB** 的实现 (`atoma-storage-mongo`)。\n\n## 核心特性\n\n- **丰富的原语支持**:\n  - **分布式锁 (`Lock`)**: 提供互斥访问，确保在任何时刻只有一个客户端可以访问共享资源。\n  - **分布式读写锁 (`ReadWriteLock`)**:允许多个读操作同时进行，但写操作是互斥的，适用于读多写少的场景。\n  - **分布式信号量 (`Semaphore`)**: 控制对共享资源的并发访问数量。\n  - **分布式倒计时门闩 (`CountDownLatch`)**: 允许一个或多个线程等待其他线程完成操作。\n  - **分布式循环栅栏 (`CyclicBarrier`)**: 让一组线程互相等待，直到所有线程都到达一个共同的屏障点。\n- **可插拔的存储后端**:\n  - 核心逻辑与存储层分离。\n  - 内置基于 MongoDB 的 `CoordinationStore` 实现。\n  - 开发者可以根据需要实现自己的存储后端，以适配不同的基础架构（如 ZooKeeper, Etcd, Redis 等）。\n- **高性能与低延迟**:\n  - 客户端与协调服务之间的通信经过优化，减少网络往返。\n  - 利用后端存储的原子操作，确保分布式环境下操作的一致性和正确性。\n- **简单易用的 API**:\n  - API 设计模仿 `java.util.concurrent`，降低学习成本。\n  - 提供 `AtomaClient` 作为统一的入口点，方便管理所有原语。\n\n## 项目架构\n\n本项目采用模块化设计，主要模块如下：\n\n- `atoma-api`: 定义了所有分布式原语的核心接口和通用异常。这是用户和实现者都应依赖的模块。\n- `atoma-core`: 提供了 Atoma 客户端的核心实现，负责与后端协调存储进行通信。\n- `atoma-storage-mongo`: 基于 MongoDB 的存储层实现，实现了 `atoma-api` 中定义的 `CoordinationStore` 接口。\n- `atoma-benchmark`: 包含一系列 JMH 基准测试，用于评估不同原语的性能。\n- `atoma-test`: 包含项目的集成测试和单元测试套件。\n\n## 快速开始\n\n### 1. 先决条件\n\n- Java 11 或更高版本。\n- 一个正在运行的 MongoDB 实例。\n\n### 2. 添加依赖\n\n**Gradle (Kotlin DSL)**\n\n```kotlin\n// build.gradle.kts\ndependencies {\n    implementation(\"io.atoma:atoma-core:1.0.0-alpha.1\")\n    implementation(\"io.atoma:atoma-storage-mongo:1.0.0-alpha.1\")\n}\n```\n\n**Maven**\n\n```xml\n\u003c!-- pom.xml --\u003e\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003etech.atoma-project\u003c/groupId\u003e\n        \u003cartifactId\u003eatoma-core\u003c/artifactId\u003e\n        \u003cversion\u003e1.0.0-alpha.1\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003etech.atoma-project\u003c/groupId\u003e\n        \u003cartifactId\u003eatoma-storage-mongo\u003c/artifactId\u003e\n        \u003cversion\u003e1.0.0-alpha.1\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n### 3. 使用示例\n\n以下是一个使用分布式互斥锁 (`MutexLock`) 的简单示例：\n\n```java\nimport atoma.api.lock.Lock;\nimport atoma.core.AtomaClient;\nimport atoma.storage.mongo.MongoCoordinationStore;\n\npublic class DistributedLockExample {\n\n    public static void main(String[] args) {\n        // 1. 创建并配置一个 MongoDB 存储后端\n        String connectionString = \"mongodb://localhost:27017\";\n        String databaseName = \"atoma_db\";\n        MongoCoordinationStore store = new MongoCoordinationStore(connectionString, databaseName);\n\n        // 2. 创建 Atoma 客户端\n        AtomaClient client = new AtomaClient.Builder()\n                .address(\"localhost\") // 标识客户端实例\n                .store(store)\n                .build();\n\n        // 3. 获取一个分布式锁实例\n        // \"my-critical-task\" 是锁的唯一名称\n        Lock mutexLock = client.getMutexLock(\"my-critical-task\");\n\n        // 4. 在 try-finally 块中获取和释放锁，确保锁一定会被释放\n        try {\n            System.out.println(\"尝试获取锁...\");\n            mutexLock.lock(); // 阻塞直到获取锁\n            System.out.println(\"成功获取锁，执行关键任务...\");\n\n            // 模拟执行任务\n            Thread.sleep(10000);\n\n            System.out.println(\"任务执行完毕。\");\n\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n            System.err.println(\"线程被中断\");\n        } finally {\n            mutexLock.unlock();\n            System.out.println(\"锁已释放。\");\n        }\n\n        // 5. 关闭客户端，释放资源\n        client.close();\n    }\n}\n```\n\n## 性能基准\n\n为了评估 `Atoma` 原语的性能，项目包含了一系列基于 [JMH (Java Microbenchmark Harness)](https://openjdk.java.net/projects/code-tools/jmh/) 的基准测试。以下是分布式互斥锁 (`MutexLock`) 在特定环境下的性能数据摘要。\n\n**测试环境:**\n\n*   **后端存储**: MongoDB\n*   **JVM**: OpenJDK 17.0.10\n\n**分布式互斥锁 (`MutexLock`) 性能:**\n\n| 基准测试 (Benchmark) | 场景 (Scenario) | 并发线程 (Threads) | 吞吐量 (Throughput) | 平均耗时 (Avg. Time) |\n| :--- | :--- | :--- | :--- | :--- |\n| `lockAndUnlock` | 无竞争 (No Contention) | 1 | ≈ 107 ops/sec | ≈ 8.7 ms/op |\n| `lockAndUnlock` | 高竞争 (High Contention) | 32 | ≈ 177 ops/sec | ≈ 464 ms/op |\n\n**结果分析:**\n\n*   **无竞争**: 在单个线程、无资源竞争的理想情况下，一次完整的加锁和解锁操作平均耗时约 8.7 毫秒。这反映了与 MongoDB 后端进行一次协调操作的基本开销。\n*   **高竞争**: 在 32 个线程并发争抢同一个锁的场景下，系统总吞吐量约为 177次/秒。虽然总吞吐量有所提升，但单次操作的平均耗时显著增加到 464 毫秒，这符合预期，因为大部分线程都处于等待锁释放的状态。\n\n这些数据表明 `Atoma` 的分布式锁在提供正确互斥保障的同时，其性能开销在分布式协调场景下是合理的。用户在设计系统时应考虑到高竞争下延迟会相应增加。\n\n## 从源码构建\n\n1. 克隆本仓库:\n   ```sh\n   git clone https://github.com/your-username/atoma.git\n   cd atoma\n   ```\n\n2. 使用 Gradle Wrapper 构建项目:\n   ```sh\n   ./gradlew build\n   ```\n   构建成功后，你可以在各个模块的 `build/libs` 目录下找到生成的 JAR 文件。\n\n## 如何贡献\n\n我们非常欢迎社区的贡献！无论是报告 Bug、提出功能建议还是提交代码。\n\n1.  **Fork** 本仓库。\n2.  创建一个新的功能分支 (`git checkout -b feature/your-feature-name`)。\n3.  进行修改并提交 (`git commit -m 'Add some feature'`)。\n4.  将你的分支推送到你的 Fork (`git push origin feature/your-feature-name`)。\n5.  创建一个 **Pull Request**。\n\n在提交 Pull Request 之前，请确保你的代码通过了所有测试 (`./gradlew test`)。\n\n## 许可证\n\n本项目采用 [Apache License 2.0](LICENSE) 许可证。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarsxuefeng%2Fatoma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarsxuefeng%2Fatoma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarsxuefeng%2Fatoma/lists"}