Skip to content

Commit 7375057

Browse files
author
Levent KARAGÖL
committed
Documentation has been updated
1 parent 4a895f4 commit 7375057

1 file changed

Lines changed: 144 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,146 @@
11
# libcpp-event-hub
2+
23
Thread-safe generic event library for C++ (17+)
4+
5+
[![linux](https://github.com/leventkaragol/libcpp-event-hub/actions/workflows/linux.yml/badge.svg)](https://github.com/leventkaragol/libcpp-event-hub/actions/workflows/linux.yml)
6+
[![windows](https://github.com/leventkaragol/libcpp-event-hub/actions/workflows/windows.yml/badge.svg)](https://github.com/leventkaragol/libcpp-event-hub/actions/workflows/windows.yml)
7+
8+
> [!TIP]
9+
> Please read this document before using the library. I know, you don't have time but reading
10+
> this document will save you time. I mean just this file, it's not long at all. Trial and error
11+
> will cost you more time.
12+
13+
# Table of Contents
14+
15+
* [What is this library used for?](#what-is-this-library-used-for)
16+
* [How to add it to my project](#how-to-add-it-to-my-project)
17+
* [How to use?](#how-to-use)
18+
* [Semantic Versioning](#semantic-versioning)
19+
* [License](#license)
20+
* [Contact](#contact)
21+
22+
## What is this library used for?
23+
24+
C++ standard library does not include a ready to use Event Handling mechanism. This library is designed to work as a
25+
singleton throughout the application and to communicate thread-safely between different code blocks via the required
26+
events with its generic structure.
27+
28+
With the Event Hub library, you can add or remove new listeners to the events, as you are used to in other languages,
29+
listen to a single event or all events from one place and emit them with the required type of data.
30+
31+
32+
## How to add it to my project?
33+
34+
This is a header only library with no external dependency. So actually, all you need is to add the libcpp-event-hub.hpp file
35+
in src folder to your project and start using it with #include.
36+
37+
You can find usage examples in the examples folder, also find a sample CMakeLists.txt file content below.
38+
39+
```cmake
40+
cmake_minimum_required(VERSION 3.14)
41+
42+
project(myProject)
43+
44+
add_executable(myProject main.cpp)
45+
46+
target_link_libraries(myProject PRIVATE libcpp-event-hub)
47+
48+
```
49+
50+
## How to use?
51+
52+
You can find a simple example of adding & deleting event listeners and emitting events to handle different types of them below.
53+
54+
```cpp
55+
#include "libcpp-event-hub.hpp"
56+
#include <string>
57+
#include <iostream>
58+
59+
using namespace lklibs;
60+
61+
int main()
62+
{
63+
// Get the singleton instance of the EventHub
64+
auto& eventHub = EventHub::getInstance();
65+
66+
// Add a listener for testEvent1, which sends a string value
67+
auto listener1Id = eventHub.addListener<std::string>("testEvent1", [](const std::string& eventName, const std::string& sender, const std::string& data)
68+
{
69+
std::cout << "1. listener received, Event name: " << eventName << ", sender: " << sender << ", data: " << data << std::endl;
70+
});
71+
72+
// Add a listener for testEvent2, which sends an int value
73+
auto listener2Id = eventHub.addListener<int>("testEvent2", [](const std::string& eventName, const std::string& sender, const int& data)
74+
{
75+
std::cout << "2 listener received, Event name: " << eventName << ", sender: " << sender << ", data: " << data << std::endl;
76+
});
77+
78+
// Add a general listener for all events with a string value
79+
auto listener3Id = eventHub.addListener<std::string>("*", [](const std::string& eventName, const std::string& sender, const std::string& data)
80+
{
81+
std::cout << "General listener received: " << eventName << ", sender: " << sender << ", data: " << data << std::endl;
82+
});
83+
84+
// Emit testEvent1 with a string value, 2 listeners will receive the event (listener1 and the general listener)
85+
eventHub.emit("testEvent1", "main", std::string("Value 1"));
86+
87+
// Emit testEvent2 with an int value, 1 listeners will receive the event (listener2), because there is no general listener for int values
88+
eventHub.emit("testEvent2", "main", 7);
89+
90+
// Remove the first listener for testEvent1
91+
eventHub.removeListener("testEvent1", listener1Id);
92+
93+
// Emit testEvent1 again, only the general listener will receive the event
94+
eventHub.emit("testEvent1", "main", std::string("Value 2"));
95+
96+
return 0;
97+
}
98+
```
99+
100+
## Semantic Versioning
101+
102+
Versioning of the library is done using conventional semantic versioning. Accordingly,
103+
in the versioning made as **MAJOR.MINOR.PATCH**;
104+
105+
**PATCH:** Includes possible Bug&Fixes and improvements. You definitely want to get this.
106+
107+
**MINOR:** Additional functionality added via backwards compatibility. You probably want to
108+
get this, it doesn't hurt.
109+
110+
**MAJOR:** Additional functionality that breaks backwards compatibility. You'll need to know
111+
what's changed before you get it, and you'll probably have to make changes to your own code.
112+
If I publish something like this, I will definitely add the changes required for migration
113+
section to the documentation.
114+
115+
## License
116+
117+
MIT License
118+
119+
Copyright (c) 2024 Levent KARAGÖL
120+
121+
Permission is hereby granted, free of charge, to any person obtaining a copy
122+
of this software and associated documentation files (the "Software"), to deal
123+
in the Software without restriction, including without limitation the rights
124+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
125+
copies of the Software, and to permit persons to whom the Software is
126+
furnished to do so, subject to the following conditions:
127+
128+
The above copyright notice and this permission notice shall be included in all
129+
copies or substantial portions of the Software.
130+
131+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
132+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
133+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
134+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
135+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
136+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
137+
SOFTWARE.
138+
139+
## Contact
140+
141+
If you have problems regarding the library, please open an
142+
[issue on GitHub](https://github.com/leventkaragol/libcpp-event-hub/issues/new).
143+
Please describe your request, issue, or question in as much detail as possible
144+
and also include the version of your compiler and operating system, as well as
145+
the version of the library you are using. Before opening a new issue, please
146+
confirm that the topic is not already exists in closed issues.

0 commit comments

Comments
 (0)