dd1f2b00c3ab6fa6c15b221d68393f104fb78915
[c11concurrency-benchmarks.git] / README.md
1 # Overview
2 `iris` is asynchronous logging library designed to log messages with minimum overhead to the performance. The cost of logging a message is merely copying the arguments into a lockfree queue.
3
4 # Design
5 Under the hood, `iris` uses a background thread (logging thread) to offload logging from other threads.
6 1. For every other threads, they keep a lockfree queue to buffer the messages.
7 2. The logging thread periodically scans through all these queues to collect messages, formats them and writes them into log file.  
8
9 A few highlights of the design of `iris` to achieve low latency:
10 1. Buffering messages with thread local lockfree queue.
11 2. Memory is managed by a thread local ringbuffer taking the advantage that logging is FIFO. Because the fact that logging is FIFO. This scales well in multithreaded environment. 
12 3. Minimum context switches.
13
14 # Usage
15 The supported severity levels are:
16 ```c++
17 enum severity_level {
18     TRACE,
19     DEBUG,
20     INFO,
21     WARN,
22     ERROR,
23     FATAL
24 };
25 ```
26 By default, `iris` logs messages to `stdout` and filters out severity level less than `INFO`.
27
28 ```c++
29 #include <iris/level_logger.h>
30
31 // this creates a logging thread, logs messages to stdout
32 iris::level_logger g_log;
33
34 int main (int argc, char const *argv[]) {
35     //configure thread level parameters, these should be done before any logging
36     // queue size
37     g_log.set_thread_queue_size(1024);
38     // ring buffer size
39     g_log.set_thread_ringbuf_size(10240);
40
41     g_log.info("Greetings from %s, bye %d\n", 'iris', 0);
42
43     //this tells logging thread to persist the data into file and waits
44     g_log.sync_and_close();
45
46     return 0;
47 }
48 ```
49 Using a `file_writer` to logs all messages into a file:
50 ```c++
51 #include <iris/level_logger.h>
52 #include <iris/file_writer.h>
53
54 iris::file_writer writer("./log.txt");
55 // this creates a logging thread
56 iris::level_logger g_log(&writer, iris::TRACE);
57
58 int main (int argc, char const *argv[]) {
59     //configure thread level parameters, these should be done before any logging
60     // queue size
61     g_log.set_thread_queue_size(1024);
62     // ring buffer size
63     g_log.set_thread_ringbuf_size(20480);
64     
65     g_log.info("Greetings from %s, bye %d\n", 'iris', 0);
66     
67     //this tells logging thread to persist the data into file and waits
68     g_log.sync_and_close();
69
70     return 0;
71 }
72 ```
73
74 # Building & Installation
75
76 To build the library, simply clone the projet, go inside the `iris` direcotry and  run following commands.
77 ```shell
78 make
79 make test
80 make install
81 ```
82 To integrate `iris` into your program, link with `-liris` options.