Events Module - Event Class

Namespace: Tiny::EV

Class Overview
Header File
Constructors
Destructor
Assignment Operator
Member Functions
EventsMap Class
Usage Examples
Notes

1. Class Overview

The Event class provides asynchronous event management functionality, supporting conditional triggering, timed delays, and repeat execution count control. It uses an independent thread internally to execute the event loop, suitable for scheduled tasks, background processing, and other scenarios.

Core Features

Conditional Triggering: Supports custom condition functions that execute only when conditions are met
Timed Execution: Configurable execution interval (milliseconds)
Repeat Control: Supports setting execution count, 0 means infinite loop
Thread Safety: Uses atomic variables to control running state
Exception Handling: Automatically catches and reports exceptions in callbacks

2. Header File

// CMake method
#include <Tiny/Events/Events.hpp>
// Direct source copy method
#include "Events/Events.hpp"

p.s: On other Unix systems, when compiling a single file, you may still need to manually include the pthread static library.

3. Constructors

3.1 Constructor with Condition

Event(uint32_t id, std::string name,
      const std::function<bool()>& condition,
      const std::function<void(const std::atomic<bool>&)>& event);

Parameter	Type	Description	Nullable
`id`	`uint32_t`	Unique event identifier	No
`name`	`std::string`	Event name	No (can be empty string)
`condition`	`std::function<bool()>`	Execution condition callback	Yes
`event`	`std::function<void(const std::atomic<bool>&)>`	Event execution callback	Yes

Description: The event callback is executed when condition returns true.

3.2 Constructor without Condition

Event(uint32_t id, std::string name,
      const std::function<void(const std::atomic<bool>&)>& event);

Parameter	Type	Description	Nullable
`id`	`uint32_t`	Unique event identifier	No
`name`	`std::string`	Event name	No
`event`	`std::function<void(const std::atomic<bool>&)>`	Event execution callback	Yes

Description: Condition defaults to [] { return true; }, meaning always execute.

3.3 Empty Event Constructor

Event(uint32_t id, std::string name);

Parameter	Type	Description	Nullable
`id`	`uint32_t`	Unique event identifier	No
`name`	`std::string`	Event name	No

Description: Only sets ID and name, setCondition() and setEvent() must be called later to set callbacks.

3.4 Copy Constructor

Event(const Event& other);

Description: Copies all properties of the source object, but resets the execution counter, does not copy thread state.

4. Destructor

virtual ~Event();

Behavior:

Automatically calls stop() to stop the event
Waits for the event thread to finish (join)
Releases thread resources

5. Assignment Operator

Event& operator=(const Event& other);

Behavior:

First stops the current event (if running)
Copies all properties of the source object
Resets the execution counter
Does not copy thread state

Return Value: Reference to self

6. Member Functions

6.1 Setter Functions

setID

void setID(uint32_t id);

Function: Set event ID
Parameter: id - New identifier
Return Value: None

setName

void setName(const std::string& name);

Function: Set event name
Parameter: name - New name
Return Value: None

setDelayMS

void setDelayMS(uint32_t delay);

Function: Set event execution interval (milliseconds)
Parameter: delay - Delay time in milliseconds, default 1000ms
Return Value: None
Notes: Modifications take effect immediately while event is running

setRepeatCount

void setRepeatCount(uint32_t count);

Function: Set repeat execution count
Parameter: count - Execution count, 0 means infinite loop
Return Value: None
Default Value: 1 (execute once)

setCondition

void setCondition(const std::function<bool()>& condition);

Function: Set execution condition
Parameter: condition - Callback function returning bool
Return Value: None
Default Condition: [] { return true; }

setAllowedFailedEnabled

void setAllowedFailedEnabled(bool enabled);

Function: Set whether failed executions are allowed
Parameter: enabled - true to allow failed executions, false to stop on failure
Return Value: None
Default Value: true (failed executions are allowed by default)

setEvent

void setEvent(const std::function<void(const std::atomic<bool>&)>& callback);

Function: Set event callback function
Parameter: callback - Event execution body, receives running state reference
Return Value: None

6.2 Query Functions

eventID

[[nodiscard]] uint32_t eventID() const;

Function: Get event ID
Return Value: Event identifier

eventName

[[nodiscard]] const std::string& eventName() const;

Function: Get event name
Return Value: Constant reference to event name

eventDelayMS

[[nodiscard]] uint32_t eventDelayMS() const;

Function: Get execution delay
Return Value: Delay in milliseconds

eventRepeatCount

[[nodiscard]] uint32_t eventRepeatCount() const;

Function: Get set repeat count
Return Value: Repeat count (0 means infinite)

executionCount

[[nodiscard]] uint32_t executionCount() const;

Function: Get the number of times the event has been executed
Return Value: Execution count

allowedFailedEnabled

[[nodiscard]] bool allowedFailedEnabled() const;

Function: Check if failed executions are allowed
Return Value: true means failed executions are allowed

isRunning

[[nodiscard]] bool isRunning() const;

Function: Check if event is running
Return Value: true means running

hasEvent

[[nodiscard]] bool hasEvent() const;

Function: Check if event callback is set
Return Value: true means callback is set

6.3 Control Functions

run

void run();

Function: Start event execution
Return Value: None
Constraints:
- Does nothing if event is already running
- Does nothing if event callback is not set
- Creates background thread on first call
- Repeated calls wake waiting threads

Execution Flow:

Check if already running, return if true
Check if event callback exists, return if not
Create background thread
Loop execution in thread:
- Check stop flag
- Check execution condition
- Execute event callback
- Wait for delay time
- Check repeat count

stop

void stop();

Function: Stop event execution
Return Value: None
Notes: Does not immediately terminate thread, only sets stop flag, event exits on next loop check

7. EventsMap Class

The EventsMap class manages multiple Event objects by their IDs.

7.1 Type Definitions

using constIter = std::unordered_map<size_t, Event>::const_iterator;

7.2 Constructors and Destructor

EventsMap();
~EventsMap();

Destructor Behavior:

Automatically calls waitAllEvents() before destruction.

7.3 Event Management

execEvent

bool execEvent(const Event& event);
bool execEvent(size_t event_id);

Function: Add and run an event, or run an existing event by ID
Return Value: true means success

addEvent

bool addEvent(const Event& event);

Function: Add an event without running it
Return Value: true means success (ID not duplicate)

removeEvent

bool removeEvent(size_t event_id);

Function: Stop and remove an event by ID
Return Value: true means success

removeAllFreeEvents

bool removeAllFreeEvents();

Function: Remove all events that are not currently running
Return Value: true

7.4 Control Functions

stopEvent

void stopEvent(size_t event_id);

Function: Stop a running event by ID

waitEvent

void waitEvent(size_t event_id);

Function: Stop and wait for an event to finish

stopAllEvents

void stopAllEvents();

Function: Stop all events in the map

waitAllEvents

void waitAllEvents();

Function: Stop and wait for all events to finish

7.5 Setter Functions

setConditionByID

bool setConditionByID(size_t event_id, const std::function<bool()>& condition);

setEventByID

bool setEventByID(size_t event_id, const std::function<void(const std::atomic<bool>&)>& event);

setDelayByID

bool setDelayByID(size_t event_id, uint32_t delay_ms);

setRepeatByID

bool setRepeatByID(size_t event_id, uint32_t repeat_count);

setAllowedFailedEnabledByID

bool setAllowedFailedEnabledByID(size_t event_id, bool enabled);

Function: Modify event properties by ID
Return Value: true means the event exists and was updated

7.6 Query Functions

exist

bool exist(size_t event_id) const;

Function: Check if an event ID exists
Return Value: true means exists

event

const Event& event(size_t event_id) const;

Function: Get event by ID
Return Value: Event reference
Exception: Throws if ID does not exist

size

size_t size() const;

Function: Get number of events in the map

eventIDList

std::vector<size_t> eventIDList() const;

Function: Get a list of all event IDs

7.7 Iterators

constIter cbegin() const;
constIter cend() const;

Function: Constant iterators over the event map

8. Usage Examples

8.1 Basic Timer

#include "Events/Events.hpp"
#include <iostream>

int main() {
    // Create timer event (execute once per second, 5 times total)
    Tiny::EV::Event timer(1, "Timer",
        [] { return true; },  // Condition: always execute
        [](const std::atomic<bool>& running) {
            if (running) {
                std::cout << "Timer tick!" << std::endl;
            }
        }
    );
    
    timer.setDelayMS(1000);  // 1 second interval
    timer.setRepeatCount(5); // Execute 5 times
    timer.run();
    
    // Wait for event completion
    std::this_thread::sleep_for(std::chrono::seconds(6));
    
    return 0;
}

8.2 Conditional Event

#include "Events/Events.hpp"
#include <iostream>
#include <atomic>

std::atomic<bool> shouldRun{false};

int main() {
    Tiny::EV::Event conditionalEvent(2, "Conditional",
        [] { return shouldRun.load(); },  // Condition: shouldRun is true
        [](const std::atomic<bool>& running) {
            std::cout << "Condition met, executing!" << std::endl;
        }
    );
    
    conditionalEvent.setDelayMS(500);
    conditionalEvent.setRepeatCount(0);  // Infinite loop
    conditionalEvent.run();
    
    // Enable condition after 3 seconds
    std::this_thread::sleep_for(std::chrono::seconds(3));
    shouldRun = true;
    
    // Run for another 5 seconds
    std::this_thread::sleep_for(std::chrono::seconds(5));
    conditionalEvent.stop();
    
    return 0;
}

8.3 Delayed Initialization Event

#include "Events/Events.hpp"
#include <iostream>

int main() {
    // Create empty event first
    Tiny::EV::Event delayedEvent(3, "Delayed");
    
    // Set callback later
    int counter = 0;
    delayedEvent.setCondition([&counter] { return counter < 10; });
    delayedEvent.setEvent([&counter](const std::atomic<bool>& running) {
        if (running) {
            std::cout << "Count: " << ++counter << std::endl;
        }
    });
    
    delayedEvent.setDelayMS(100);
    delayedEvent.run();
    
    // Wait for completion
    while (delayedEvent.isRunning()) {
        std::this_thread::sleep_for(std::chrono::milliseconds(10));
    }
    
    return 0;
}

8.4 Multiple Event Management

#include "Events/Events.hpp"
#include <iostream>
#include <vector>

int main() {
    std::vector<Tiny::EV::Event> events;
    
    // Create multiple timers
    for (int i = 0; i < 3; ++i) {
        events.emplace_back(i, "Timer" + std::to_string(i));
        events[i].setDelayMS(1000 * (i + 1));
        events[i].setRepeatCount(3);
        events[i].setEvent([i](const std::atomic<bool>&) {
            std::cout << "Event " << i << " triggered!" << std::endl;
        });
        events[i].run();
    }
    
    // Wait for all events to complete
    std::this_thread::sleep_for(std::chrono::seconds(10));
    
    return 0;
}

9. Notes

9.1 Thread Safety

Event class member functions are not thread-safe
Do not modify event properties in the event callback
Use atomic variables or mutexes to protect shared data

9.2 Exception Handling

Exceptions in event callbacks are caught and output to stderr:

Event event(1, "Test", [](const std::atomic<bool>&) {
    throw std::runtime_error("Error!");
});
// Output: "Tiny::Event: An error has occurred: Error!"

9.3 Stopping Events

stop() only sets the stop flag, does not forcefully terminate the thread
Event exits on next loop check
If event is executing callback, waits for callback completion

9.4 Resource Management

Destructor automatically calls stop() and waits for thread completion
Avoid destroying event objects while event is running
When using smart pointers to manage event objects, ensure sufficient lifetime

9.5 Delay Settings

setDelayMS() can be modified while event is running
Changes take effect on next wait
Minimum delay is affected by system scheduling, should not be set too small (< 10ms)

FilesExpand file tree

Event.md

Latest commit

History