{"id":25191645,"url":"https://github.com/nikomalik/mutex","last_synced_at":"2025-09-23T09:44:19.638Z","repository":{"id":255438986,"uuid":"850712157","full_name":"NikoMalik/mutex","owner":"NikoMalik","description":"Faster implementations for mutex","archived":false,"fork":false,"pushed_at":"2024-09-02T12:00:08.000Z","size":17,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T12:51:52.332Z","etag":null,"topics":["go","golang","golang-library","mutex","mutex-lock","sync"],"latest_commit_sha":null,"homepage":"","language":"Go","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/NikoMalik.png","metadata":{"files":{"readme":"README.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}},"created_at":"2024-09-01T15:11:34.000Z","updated_at":"2024-09-02T12:00:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"cff86cc5-1bc2-424c-b6c3-1af63dd2a5fa","html_url":"https://github.com/NikoMalik/mutex","commit_stats":null,"previous_names":["nikomalik/mutex"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/NikoMalik/mutex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikoMalik%2Fmutex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikoMalik%2Fmutex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikoMalik%2Fmutex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikoMalik%2Fmutex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NikoMalik","download_url":"https://codeload.github.com/NikoMalik/mutex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NikoMalik%2Fmutex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276554022,"owners_count":25662960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["go","golang","golang-library","mutex","mutex-lock","sync"],"created_at":"2025-02-09T22:35:52.579Z","updated_at":"2025-09-23T09:44:19.590Z","avatar_url":"https://github.com/NikoMalik.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MutexExp and ShardedMutex Documentation\n\n## Overview\n\nThis package provides two mutex implementations: `MutexExp` and `ShardedMutex`. These implementations are designed for efficient locking in concurrent applications where minimizing contention is critical.\n\n### MutexExp\n\n`MutexExp` is a simple spinlock implementation that avoids the overhead associated with traditional blocking mutexes. It is designed for situations where the lock is held for a very short time and where spinning is more efficient than context switching.\n\n### ShardedMutex\n\n`ShardedMutex` is a composite mutex that distributes locks across multiple \"shards\" or smaller mutexes (`MutexExp`). This design reduces contention by allowing multiple operations to proceed in parallel as long as they target different shards. It's particularly useful in scenarios where you have a large number of independent keys or resources that need to be locked concurrently.\n\n---\n\n## MutexExp\n\n### Fields\n\n- `i int32`: The internal state of the mutex. A value of `0` indicates the mutex is unlocked, while `1` indicates it is locked.\n- `_[CacheLinePadSize]byte`: Padding to avoid false sharing between processors. This ensures that the `MutexExp` structure occupies its own cache line, reducing contention on multi-core systems.\n\n### Methods\n\n- `get() int32`: Safely retrieves the current state of the mutex using atomic operations.\n- `set(i int32)`: Safely sets the state of the mutex using atomic operations.\n- `Lock()`: Attempts to acquire the lock. If the lock is not immediately available, it spins for a short period before yielding the processor and, eventually, sleeping to reduce CPU usage.\n- `Unlock()`: Releases the lock. If the lock is already unlocked, it panics, indicating a logic error in the program.\n\n### Advantages\n\n- **Low overhead**: Spinlocks can be more efficient than traditional mutexes in low-contention scenarios where locks are held for a very short duration.\n- **No context switching**: Since `MutexExp` avoids blocking, it can be more efficient in high-performance applications where context switching would add significant overhead.\n\n### Risks\n\n- **CPU usage**: In high-contention scenarios, `MutexExp` can cause excessive CPU usage as threads spin while waiting for the lock.\n- **Potential deadlock**: If `Unlock` is not called correctly, it can result in a deadlock, especially since there is no way to detect misuse at compile time.\n- **Limited use cases**: Spinlocks are best suited for short critical sections. If the critical section takes too long, it can negate the benefits of using a spinlock.\n\n---\n\n## ShardedMutex\n\n### Fields\n\n- `shards []MutexExp`: An array of `MutexExp` instances. Each shard can be locked independently, allowing multiple threads to operate on different shards concurrently.\n- `count int`: The number of shards. Determines the level of granularity for locking.\n\n### Methods\n\n- `NewShardedMutex(shardCount int) *ShardedMutex`: Initializes a new `ShardedMutex` with the specified number of shards.\n- `GetShard(key int) *MutexExp`: Computes the shard index based on the given key and returns the corresponding `MutexExp` instance.\n- `Lock(key int)`: Acquires the lock for the shard corresponding to the given key.\n- `Unlock(key int)`: Releases the lock for the shard corresponding to the given key.\n\n### Advantages\n\n- **Reduced contention**: By sharding the mutex, `ShardedMutex` reduces the chance of contention, allowing multiple threads to lock different shards concurrently.\n- **Scalability**: This approach scales well with the number of threads, as the probability of contention decreases with the number of shards.\n\n### Risks\n\n- **Hash collisions**: If the keys map to the same shard, the benefits of sharding are reduced. Proper key distribution is crucial to avoid hot spots.\n- **Complexity**: The use of sharded locks introduces additional complexity in managing and ensuring that the correct shard is locked for a given operation.\n- **Partial locking**: If multiple resources are accessed that map to different shards, there is a risk of deadlock if locks are not acquired and released in a consistent order.\n\n---\n\n## Usage Scenarios\n\n### MutexExp\n\n- **Low-latency applications**: Where locking time is very short, and the overhead of context switching must be avoided.\n- **High-performance code**: Where avoiding the overhead of blocking mutexes can result in significant performance gains.\n\n### ShardedMutex\n\n- **Concurrent data structures**: Ideal for data structures like hash tables, where different keys can be locked independently.\n- **High-contention environments**: Where traditional locking mechanisms would result in excessive contention and reduced performance.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikomalik%2Fmutex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikomalik%2Fmutex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikomalik%2Fmutex/lists"}