mirror of
https://github.com/matrix-construct/construct
synced 2024-11-10 20:11:07 +01:00
60 lines
2.9 KiB
Markdown
60 lines
2.9 KiB
Markdown
# IRCd Library
|
|
|
|
This library can be embedded by developers creating their own server or those
|
|
who simply want to use the library of routines it provides. See the section for
|
|
`Using libircd`.
|
|
|
|
The purpose of `libircd` is to facilitate the execution of a server which
|
|
handles requests from end-users. The library hosts a set of pluggable modules
|
|
which may introduce the actual application features (or the "business logic")
|
|
of the server. These additional modules are found in the `modules/` directory;
|
|
|
|
### Using libircd
|
|
|
|
##### libircd can be embedded in your application with very minimal overhead.
|
|
|
|
This allows you to customize and extend the functionality of the server and have
|
|
control over its execution, or, simply use library routines provided by the library
|
|
without any daemonization. Including libircd headers will not include any other
|
|
headers beyond those in the standard library, with minimal impact on your project's
|
|
compile complexity. The prototypical embedding of `libircd` is `charybdis` found in
|
|
the `charybdis/` directory.
|
|
|
|
##### libircd runs only one server at a time.
|
|
|
|
Keeping with the spirit of simplicity of the original architecture, `libircd`
|
|
continues to be a "singleton" object which uses globals and keeps actual server
|
|
state in the library itself. In other words, **only one IRC daemon can exist
|
|
within a process's address space at a time.** This is actually a profitable
|
|
design decision for making IRCd easier to understand for contributors.
|
|
|
|
##### libircd is single-threaded✝
|
|
|
|
The library is based around the `boost::asio::io_service` event loop. It is still
|
|
an asynchronous event-based system. We process one event at a time; developers must
|
|
not block execution. Events are never processed concurrently on different threads.
|
|
|
|
✝ If there is ever a truly long-running computation or a call to a 3rd party
|
|
library which will do IO and block the event loop, we may use an additional
|
|
`std::thread` to "offload" this operation.
|
|
|
|
##### libircd introduces userspace threading✝
|
|
|
|
IRCd presents an interface introducing stackful coroutines, a.k.a. userspace context
|
|
switching, or green threads. The library avoids callbacks as the way to break up
|
|
execution when waiting for events. Instead, we harken back to the simple old ways
|
|
of synchronous programming where control flow and data are easy to follow.
|
|
|
|
✝ If there are certain cases where we don't want a stack to linger which may
|
|
jeopardize the c10k'ness of the daemon the asynchronous pattern is still used.
|
|
|
|
##### libircd innovates with formal grammars
|
|
|
|
We leverage the boost::spirit system of parsing and printing through formal grammars,
|
|
rather than writing our own parsers manually. In addition, we build several tools
|
|
on top of such formal devices like a type-safe format string library acting as a
|
|
drop-in for ::sprintf(), but accepting objects like std::string without .c_str()
|
|
and prevention of outputting unprintable/unwanted characters that may have been
|
|
injected into the system somewhere prior.
|
|
|
|
|