Home

What Is EpollTimer Library?

This library provides an efficient and scalable epoll-based timer framework. Moreover, the threads optimize the cost of scheduling a new timer because the newly scheduled timers are not directly inserted into the timer's main storage. This minimizes the critical section between threads with a minimum wait time. In addition, canceling the timers is incredibly easy, requiring only one method call.

Technical Details

EpollTimer has a simple design and provides an easy-to-use set of APIs with great flexibility in payload data management. This section explains the important concepts and components provided by the EpollTimer library.

TimerTaskProxy

This class provides an abstraction of the internally managed TimerTask object. Any action by the client must be performed through this class for a scheduled timer task. The public methods provided by this class are all thread-safe. This object is created by the EpollTimerScheduler class if the desired timer is scheduled successfully.

EpollTimerScheduler

This class is mainly responsible for scheduling the timers and introducing them to the framework. This class can access the special private methods of the TimerTaskProxy class to manage the life cycle of the scheduled timer object.

Dependency

EpollTimer only requires Boost's intrusive container component. This is because the timer stores the scheduled objects in an intrusive container.

Building

EpollTimer provides a config file package that can be used by downstream. Specify CMAKE_INSTALL_PREFIX to install the library in the desired directory. Tests can be compiled by setting the ENABLE_TEST option. Note that the UTs take some time to perform because of the random timers.

git clone [email protected]:SelcukAydi/epoll-timer.git
cd epoll-timer
mkdir build
cmake -DCMAKE_INSTALL_PREFIX=<your-path-to-install> -ENABLE_TEST=ON|OFF ../
make install

Using EpollTimer

The library can easily be integrated into your project by just calling find_package in CMake. Example usage:

find_package(EpollTimer 1.0.0 CONFIG REQUIRED)

if(TARGET sia::epoll::EpollTimer)
  message(STATUS "Found EpollTimer config at: ${EpollTimer_DIR}")
  message(STATUS "Found EpollTimer full version:${EpollTimer_VERSION}")
else()
  message(FATAL_ERROR "EpollTimer config not found.")
endif()
target_link_libraries(${PROJECT_NAME} sia::epoll::EpollTimer)

Code Example

More examples can be found in the test folder.

Scheduling a Simple Timer

auto callback_on_timer = 
    [](const std::shared_ptr<sia::epoll::timer::TimerTaskProxy>& task, sia::epoll::timer::Reason reason)
    {
        if (reason == sia::epoll::timer::Reason::kExpire)
        {
            std::cout << "Timer expired\n";
        }
        else if (reason == sia::epoll::timer::Reason::kCancel)
        {
            std::cout << "Timer cancelled\n";
        }
    };

sia::epoll::timer::EpollTimer timer;
sia::epoll::timer::EpollTimerScheduler scheduler{timer};
auto result = scheduler.schedule(std::chrono::milliseconds{100}, callback_on_timer);
assert(result.first == sia::epoll::timer::Status::kSuccess);
assert(result.second != nullptr);
timer.loopConsumeAll();