Weave

Concurrency for C++

Acknowledgements

This library was created based on my solutions for problems from the MIPT concurrency course. Major part of tests comes from the same course.

Original design (including this readme): await by Roman Lipovsky.

Features

• Scalable work-stealing scheduler – executors::tp::fast::ThreadPool
• Transparent stackful fibers via executors::fibers::ThreadPool with automatic pooling
• Functional futures with almost everything deduced in compile-time
• Futures are lazy ⟹ allocation and synchronization is minimized (usually to zero)
• Transparent cooperative cancellation, wait-free for sequential composition and lock-free for parallel composition
• Structured concurrency via parallel combinators ('All', 'First', etc)
• Deterministic stress-tests with fault-injection via Twist framework

Contents

• Executors
  • Thread Pools (ThreadPool)
    • tp::compute::ThreadPool with shared blocking queue for independent CPU-bound tasks
    • Scalable work-stealing tp::fast::ThreadPool for fibers / stackless coroutines (IO-bound tasks)
  • Strand (asynchronous mutex)
  • ManualExecutor for deterministic testing
  • Transparent fibers (fibers)
    • fibers::ThreadPool
    • fibers::ManualExecutor
• Futures
  • Types (types)
    • concepts SomeFuture, Future<T>, EagerFuture
    • BoxedFuture<T>
  • Constructors (make)
    • After
    • Contract + Promise<T>
    • Failure
    • Just
    • Never
    • Submit
    • Value
  • Combinators (combine)
    • Sequential composition (seq)
      • Map / AndThen / OrElse – monadic mappers for Result<T>
      • Flatten – flattens nested futures (for asynchronous mappers)
      • FlatMap = Map + Flatten
      • Via – sets executor and/or hint for following mappers
      • Box – erases concrete Future (Thunk) type
      • Start (or Force) – converts to EagerFuture, starts operation
      • Fork<N> – splits future value into N copies
      • OnComplete / OnCancel / Anyway – add side effect
      • WithTimeout – attaches timeout
    • Parallel composition (par)
      • All/Both
      • First
      • Select (std::variant alternative to First which records first finished future (even if there was an error))
      • Quorum (blocking)
      • no_alloc versions which saves up allocations at the cost of less intuitive semantics
  • Terminators (run)
    • Await – synchronously unwraps Result from future
    • Detach – moves future on the stack and starts it without cancelling it
    • Discard – moves future on the stack, starts it and cancels it
  • Operators (syntax)
    • pipe: Just() | Via(pool) | Apply([]{})
    • bang: !f ~ f | Start()
    • or: f or g ~ FirstOf(f, g)
    • sum: f + g ~ All(f, g)
• Stackful Fibers
  • Scheduling (sched)
    • Yield
    • SleepFor
  • Synchronization (sync)
    • Mutex (lock-free)
    • OneShotEvent (lock-free)
    • WaitGroup (lock-free)
    • Buffered Channel<T> + Select
    • Lock-free unbuffered experimental::Channel<T>
• Timers

Examples

• Futures
• Executors
• Fibers
• Cancellation
• Timers

Docs

• Getting started
• Advanced features
• Unit tests

Requirements

	Supported
Architecture	x86-64
Operating System	Linux
Compiler	Clang++ (≥ 14)

Dependencies

• Wheels – core components, test framework
• Sure – context switching for stackful fibers / coroutines
• Twist – fault injection framework for concurrency
• expected - error handling
• Mimalloc – memory allocation
• function2 – drop-in replacement for std::function
• fmt – formatted output