ep_engine — epoll-based Event Engine

A lightweight event engine built on Linux epoll.

Overview

ep_engine provides a minimal event-driven execution model for handling I/O events using Linux’s epoll interface.

File descriptors registered with the engine are associated with callbacks that are invoked when I/O events occur.

The engine is intended as a small building block for experimental event-driven systems rather than a general-purpose event framework.

Design Context

This engine was developed as a foundational component for the distributed systems prototype stack.

In that stack, it serves as the underlying event engine used by higher-level components such as the message-passing layer.

Although originally developed for that environment, the engine can also be used in other event-driven applications.

Event Handling Model

The engine operates in edge-triggered mode.

Applications using the engine should follow the general approach recommended for edge-triggered epoll usage:

• File descriptors should be set to non-blocking mode
• When handling an event, the application should read/write the file descriptor until EAGAIN
• After the event has been fully handled, the application must re-arm the event to receive further notifications.

Core Concepts

Epolled_fd

Epolled_fd represents a file descriptor managed by the engine.

Each instance maintains internal read/write event objects that track the state of pending I/O events and registered handlers.

Event States

State	Description
EV_HANDLER_ARMED	A handler is registered and will be scheduled when the event occurs.
EV_NOT_AVAILABLE	No event is currently available.
EV_AVAILABLE	An event has occurred but is not yet handled.
EV_CLOSED	The event is no longer tracked.

Key APIs

epdfd_notify_on_read() / epdfd_notify_on_writable()

Registers a callback to be invoked when the file descriptor becomes readable or writable.

After a callback handles an event, the application must call the notification function again to receive future events.

epdfd_set_read() / epdfd_set_writable()

Marks the file descriptor as ready and schedules the corresponding callback if one is registered.

These functions are used internally when the event loop detects readiness.

Event Loop

The event loop waits for I/O events using epoll_wait() and schedules callbacks when events occur.

Depending on configuration, callbacks may either:

• execute directly within the event loop, or
• be dispatched to a thread pool for concurrent execution.

Notes

This project is intended for experimental use and does not aim to provide production-level event loop functionality.

Error handling and edge-case coverage are intentionally minimal.

Dependencies:

• utils — helper utilities and small data structures used internally
• pthread

The CMake configuration automatically fetches the dependencies.

Build and Installation

# 1. Clone the repository
git clone https://github.com/wjnlim/ep_engine.git

# 2. Create a build directory
mkdir ep_engine/build
cd ep_engine/build

# 3. Configure with CMake
cmake -DCMAKE_INSTALL_PREFIX=<your install directory> ..

# 4. Build and install
cmake --build . --target install

Example Program

An example program demonstrating basic usage is provided in the repository:

• tests/ep_engine_demo.c

To compile a program using this library:

gcc your_prog.c -o your_prog -I <your install directory>/include \
  <your install directory>/lib/libep_engine.a -lpthread