added README and LICENSE
This commit is contained in:
7
LICENSE
Normal file
7
LICENSE
Normal file
@@ -0,0 +1,7 @@
|
||||
Copyright (c) 2026 Peisong Xiao
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
119
README.md
Normal file
119
README.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# ThreadWeaver - Lock-Free Multi-Thread Communication Templates
|
||||
A collection of lock-free intra-thread message-sending fabrics
|
||||
including SPSC, MPSC and SPMC templates, targeting x64 and ARMv8+
|
||||
platforms.
|
||||
|
||||
The implementation avoids CAS retry loops and ensures a linearly
|
||||
bounded number of operations for fairness, leading to bounded latency
|
||||
for any request to be processed. Fairness here means that no producer
|
||||
or consumer can be perpetually starved under continuous contention.
|
||||
|
||||
Some variations of the same actions are provided for fine-tuning
|
||||
performance.
|
||||
|
||||
## Table of Contents
|
||||
- [ThreadWeaver – Lock-Free Multi-Thread Communication Templates](#threadweaver---lock-free-multi-thread-communication-templates)
|
||||
- [Requirements](#requirements)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Explicitness](#explicitness)
|
||||
- [Important Messages](#important-messages)
|
||||
- [External Synchronization](#external-synchronization)
|
||||
- [Variations](#variations)
|
||||
- [Common Verbs](#common-verbs)
|
||||
- [`[sync] init`](#sync-init)
|
||||
- [`[sync] flush`](#sync-flush)
|
||||
- [`send`](#send)
|
||||
- [`recv`](#recv)
|
||||
- [Design and Inspiration](#design-and-inspiration)
|
||||
|
||||
## Requirements
|
||||
The Weaver library requires a compiler supporting C++20 and above
|
||||
standards.
|
||||
|
||||
## Quick Start
|
||||
Weaver is contained within one header in [weaver.h](include/weaver.h)
|
||||
to accommodate C++ specific template instantiation requirements.
|
||||
|
||||
The user must provide the cache line size
|
||||
`--param=destructive-interference-size` or configure the static
|
||||
`THWeaver::CLS` parameter in order to compile with the library. This
|
||||
is to ensure correct cache line isolation and avoid false sharing
|
||||
across platforms.
|
||||
|
||||
**We will use the term "fabric" to refer to instantiated communication
|
||||
objects from the Weaver library.**
|
||||
|
||||
The included classes are:
|
||||
1. SPSC: `THWeaver::EndpointQueue`
|
||||
2. MPSC: `THWeaver::FanInFabric`
|
||||
3. SPMC: `THWeaver::FanOutFabric`
|
||||
|
||||
See [docs](docs/) for more detailed documentation on the classes and
|
||||
result enums.
|
||||
|
||||
### Explicitness
|
||||
The Weaver library expects that the user explicitly state the
|
||||
behavior for the fabric and does not rely on automatic constructors
|
||||
and destructors for state initialization and resource management.
|
||||
|
||||
### Important Messages
|
||||
Throughout the documentation (including this README), all important
|
||||
messages will have a leading "IMPORTANT".
|
||||
|
||||
Violations of important messages may result in **undefined behavior**.
|
||||
|
||||
### External Synchronization
|
||||
Some non-critical Weaver methods may expect external synchronization,
|
||||
oriented towards control-plane usage rather than the actual data-plane
|
||||
pipelines.
|
||||
|
||||
Use of these methods without synchronization may result in **undefined
|
||||
behaviors**.
|
||||
|
||||
These operations are marked by `[sync]`.
|
||||
|
||||
### Variations
|
||||
All class methods are named by `verb[_variation]`, and different
|
||||
variations of the same action may have different costs.
|
||||
|
||||
This document will only contain an overview on the verb (action),
|
||||
please see [docs](docs/) for detailed views on variations
|
||||
|
||||
### Common Verbs
|
||||
The verbs listed below are universal to all Weaver classes.
|
||||
|
||||
#### `[sync] init`
|
||||
Explicitly initialize the fabric.
|
||||
|
||||
**IMPORTANT: This method is expected to only be called once during
|
||||
the fabric's lifetime.**
|
||||
|
||||
#### `[sync] flush`
|
||||
Reset the fabric or part of the fabric.
|
||||
|
||||
#### `send`
|
||||
Moves a message into the fabric. The return type will explicitly
|
||||
inform if and how it failed.
|
||||
|
||||
#### `recv`
|
||||
Moves a message out of the fabric or initializes a token to the
|
||||
message. The return type will explicitly inform if and how it failed.
|
||||
|
||||
## Design and Inspiration
|
||||
Weaver is designed for the current generation and architecture of
|
||||
hardware and does not provide upwards compatibility to future
|
||||
hardware. It assumes multi-level caching and high-cost of memory
|
||||
operations, and aims to reduce memory and cache coherence traffic by
|
||||
respecting the hardware cache architecture.
|
||||
|
||||
And to ensure fairness for multiple producer or consumer threads,
|
||||
Weaver includes simple scheduling that degrades into round-robin
|
||||
schemes in the worst case.
|
||||
|
||||
It is inspired by networking concepts and hardware clock domain
|
||||
crossing implementations. And for each operation, it tries to keep
|
||||
modifications monotonic and data-flow unidirectional.
|
||||
|
||||
Shared states that must be lossless are structured so that operations
|
||||
are causally ordered and monotonic, allowing simpler synchronization
|
||||
and reduced coherence traffic.
|
||||
@@ -1,3 +1,25 @@
|
||||
/*
|
||||
* Copyright (c) 2026 Peisong Xiao
|
||||
*
|
||||
* Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
* of this software and associated documentation files (the "Software"), to deal
|
||||
* in the Software without restriction, including without limitation the rights
|
||||
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
* copies of the Software, and to permit persons to whom the Software is
|
||||
* furnished to do so, subject to the following conditions:
|
||||
*
|
||||
* The above copyright notice and this permission notice shall be included in
|
||||
* all copies or substantial portions of the Software.
|
||||
*
|
||||
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
* SOFTWARE.
|
||||
*/
|
||||
|
||||
#ifndef THREADWEAVER_WEAVER_H
|
||||
#define THREADWEAVER_WEAVER_H
|
||||
|
||||
@@ -56,7 +78,7 @@ public:
|
||||
tail.store(0, std::memory_order_release);
|
||||
}
|
||||
|
||||
std::size_t size() const noexcept {
|
||||
std::size_t get_size() const noexcept {
|
||||
return ((tail.load(std::memory_order::acquire) + QSIZE_MASK) -
|
||||
head.load(std::memory_order::acquire)) &
|
||||
QSIZE_MASK;
|
||||
@@ -291,23 +313,23 @@ public:
|
||||
|
||||
uint8_t curr = dl.first;
|
||||
|
||||
if (in_queues[curr].size())
|
||||
if (in_queues[curr].get_size())
|
||||
bitmap |= BitmapType(1) << curr;
|
||||
|
||||
do {
|
||||
curr = dl.next[curr];
|
||||
if (in_queues[curr].size())
|
||||
if (in_queues[curr].get_size())
|
||||
bitmap |= BitmapType(1) << curr;
|
||||
} while (curr != dl.last);
|
||||
|
||||
hint.fetch_or(bitmap, std::memory_order_relaxed);
|
||||
}
|
||||
|
||||
template <std::size_t thread_id> std::size_t size() const noexcept {
|
||||
template <std::size_t thread_id> std::size_t get_size() const noexcept {
|
||||
static_assert(thread_id < IN_THREAD_CNT,
|
||||
"Thread ID out of bounds");
|
||||
|
||||
return in_queues[thread_id].size();
|
||||
return in_queues[thread_id].get_size();
|
||||
}
|
||||
|
||||
template <std::size_t thread_id> bool is_empty() const noexcept {
|
||||
@@ -510,12 +532,12 @@ public:
|
||||
BorrowedRef<thread_id> get_empty_borrowed_ref() const noexcept {
|
||||
return BorrowedRef<thread_id>();
|
||||
}
|
||||
IndexType free_size() const noexcept { return fs.size(); }
|
||||
template <std::size_t thread_id> std::size_t size() const noexcept {
|
||||
IndexType free_get_size() const noexcept { return fs.get_size(); }
|
||||
template <std::size_t thread_id> std::size_t get_size() const noexcept {
|
||||
static_assert(thread_id < OUT_THREAD_CNT,
|
||||
"Thread ID out of bounds");
|
||||
|
||||
return consumer_queues[thread_id].size();
|
||||
return consumer_queues[thread_id].get_size();
|
||||
}
|
||||
|
||||
FanOutFabricSendResult<BitmapType>
|
||||
@@ -671,9 +693,9 @@ private:
|
||||
OUT_THREAD_CNT>
|
||||
consumer_queues;
|
||||
alignas(CLS) std::atomic<BitmapType> reclaim_hint;
|
||||
struct alignas(CLS) BufferSlot {
|
||||
std::atomic<RefCountType> count;
|
||||
MessageType payload;
|
||||
struct BufferSlot {
|
||||
alignas(CLS) MessageType payload;
|
||||
alignas(CLS) std::atomic<RefCountType> count;
|
||||
};
|
||||
std::array<BufferSlot, BUFFER_SIZE> buffer;
|
||||
struct alignas(CLS) FreeStack {
|
||||
@@ -695,7 +717,7 @@ private:
|
||||
}
|
||||
IndexType pop_unsafe() { return free[--top]; }
|
||||
bool is_empty() const { return top == 0; }
|
||||
int size() const { return top; }
|
||||
int get_size() const { return top; }
|
||||
} fs;
|
||||
std::size_t reclaim_rot;
|
||||
|
||||
|
||||
Reference in New Issue
Block a user