odyssey/third_party/machinarium/README.md

Machinarium

Machinarium allows to create fast networked and event-driven asynchronous applications in synchronous/procedural manner instead of using traditional callback approach.

Public API ⇨ sources/machinarium.h

Threads and coroutines

Machinarium is based on combination of pthreads(7) and custom made implementation of efficient cooperative multi-tasking primitives (coroutines).

Each coroutine executed using own stack context and transparently scheduled by epoll(7) event-loop logic. Each working Machinarium thread can handle thousands of executing coroutines.

Messaging and Channels

Machinarium messages and channels are used to provide IPC between threads and coroutines. Ideally, this approach should be sufficient to fulfill needs of most multi-threaded applications without the need of using additional access synchronization.

Efficient TCP/IP networking

Machinarium IO API primitives can be used to develop high-performance client and server applications. By doing blocking IO calls, currently executing coroutine suspends and switches to a next one ready to go. When the original request completed, timedout or cancel event happened, coroutine resumes.

One of the main goals of networking API design is performance. To reduce number of system calls read operation implemented with readahead support. It is fully buffered and transparently continue to read socket data even when no active calls are in progress, to reduce epoll(7) subscribe overhead.

Machinarium IO contexts can be transferred between threads, which allows to develop efficient producer-consumer network applications.

Full-featured SSL/TLS support

Machinarium has easy-to-use Transport Layer Security (TLS) API methods.

Create Machinarium TLS object, associate it with any existing IO context and the connection will be automatically upgraded.

DNS resolving

Machinarium implements separate thread-pool to run network address and service translation functions such as getaddrinfo(), to avoid process blocking and to be consistent with coroutine design.

Timeouts and Cancellation

All blocking Machinarium API methods are designed with timeout flag. If operation does not complete during requested time interval, then method will return with appropriate errno status set.

Additionally, a coroutine can Cancel any on-going blocking call of some other coroutine. And as in timeout handling, cancelled coroutine method will return with appropriate status.