/** \brief Singleton class to manage the event loop
- The Scheduler singleton manages the central event loop. It manages and dispatches all types
+ The %scheduler singleton manages the central event loop. It manages and dispatches all types
of events managed by the scheduler library:
\li File descriptor notifications
\li Timeouts
\li UNIX Signals
- The scheduler is entered by calling it's process() member. This call will continue to run as
+ The %scheduler is entered by calling it's process() member. This call will continue to run as
long as there is something to do, or until one of the handlers calls terminate(). The
- Scheduler has 'something to do' as long as there is any file descriptor or timeout active.
+ %scheduler has 'something to do' as long as there is any file descriptor or timeout active.
- The Scheduler only provides low level primitive scheduling capability. Additional helpers
+ The %scheduler only provides low level primitive scheduling capability. Additional helpers
are defined on top of this functionality (e.g. ReadHelper or WriteHelper or the interval
timers of the PPI).
All handlers are passed as generic <a
href="http://www.boost.org/doc/html/function.html">Boost.Function</a> objects. This allows
to pass any callable as a handler. Depending on the type of handler, some additional
- arguments may be passed to the handler by the scheduler.
+ arguments may be passed to the handler by the %scheduler.
If you need to pass additional information to your handler, use <a
href="http://www.boost.org/libs/bind/bind.html">Boost.Bind</a>:
Only a single handler may be registered for any combination of file descriptor and event
(registering multiple callbacks for a single fd and event does not make sense).
- The scheduler will accept any object as \a handle argument as long as retrieve_filehandle()
+ The %scheduler will accept any object as \a handle argument as long as retrieve_filehandle()
may be called on that object
\code
int fd = retrieve_filehandle(handle);
\section sched_timers Registering timers
- The Scheduler has very simple timer support. There is only one type of timer: A single-shot
+ The %scheduler has very simple timer support. There is only one type of timer: A single-shot
deadline timer. More complex timers are built based on this. Timers are managed using
timeout() and cancelTimeout()
\code
There are two parameters which adjust the exact: \a timeoutEarly and \a timeoutAdjust. \a
timeoutEarly is the time, a callback may be called before the deadline time is
reached. Setting this value below the scheduling granularity of the kernel will have the
- scheduler go into a <em>busy wait</em> (that is, an endless loop consuming 100% of CPU
+ %scheduler go into a <em>busy wait</em> (that is, an endless loop consuming 100% of CPU
recources) until the deadline time is reached! This is seldom desired. The default setting
of 11ms is adequate in most cases (it's slightly above the lowest linux scheduling
granularity).
\section sched_signals Registering POSIX/UNIX signals
- The Scheduler also incorporates standard POSIX/UNIX signals. Signals registered with the
- scheduler will be handled \e synchronously within the event loop.
+ The %scheduler also incorporates standard POSIX/UNIX signals. Signals registered with the
+ %scheduler will be handled \e synchronously within the event loop.
\code
Scheduler::instance().registerSignal(SIGUSR1, &callback);
Scheduler::instance().unregisterSignal(SIGUSR1);
\endcode
- When registering a signal with the scheduler, that signal will automatically be blocked so
- it can be handled within the scheduler.
+ When registering a signal with the %scheduler, that signal will automatically be blocked so
+ it can be handled within the %scheduler.
A registered signal does \e not count as 'something to do'. It is therefore not possible to
wait for signals \e only.
// default destructor
// no conversion constructors
- /** \brief Return Scheduler instance
+ /** \brief Return %scheduler instance
This static member is used to access the singleton instance. This member is save to
- return a correctly initialized Scheduler instance even if called at global construction
+ return a correctly initialized %scheduler instance even if called at global construction
time
- \implementation This static member just defines the Scheduler as a static method
+ \implementation This static member just defines the %scheduler as a static method
variable. The C++ standard then provides above guarantee. The instance will be
initialized the first time, the code flow passes the variable declaration found in
the instance() body.
template <class Handle>
void add(Handle const & handle, FdCallback const & cb,
int eventMask = EV_ALL); ///< Add file handle event callback
- /**< add() will add a callback to the Scheduler. The
+ /**< add() will add a callback to the %scheduler. The
callback will be called for the given type of event on
the given arbitrary file-descriptor or
handle-like object. If there already is a Callback
/** \brief Default file descriptor accessor
- retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
+ retrieve_filehandle() provides the %scheduler with support for explicit file descriptors as
file handle argument.
\relates Scheduler
*/
int retrieve_filehandle(int fd);
- /** \brief Scheduler specific time source for Utils/Logger framework
+ /** \brief %scheduler specific time source for Utils/Logger framework
This time source may be used to provide timing information for log messages within the
Utils/Logger framework. This time source will use Scheduler::eventTime() to provide timing
/** \defgroup loglevels Log levels
- These are the valid log levels with some additional special values:
+ These are the valid %log levels with some additional special values:
- <dl><dt>VERBOSE</dt><dd>Really verbose log messages. Messages at this level are used for
+ <dl><dt>VERBOSE</dt><dd>Really verbose %log messages. Messages at this level are used for
internal debugging. They should be enabled only selectively within the areas currently under
inspection.</dd>
<dt>FATAL</dt><dd>Error condition which does terminate program execution or enforces a
restart or some kind of re-initialization with loss of state and context.</dd></dl>
- There are also some special values which <em>must not be used as a log level</em>:
+ There are also some special values which <em>must not be used as a %log level</em>:
- <dl><dt>DISABLED</dt><dd>Disable all log messages.</dd>
+ <dl><dt>DISABLED</dt><dd>Disable all %log messages.</dd>
- <dt>NONE</dt><dd>Special value which signifies inheritance of the default log
+ <dt>NONE</dt><dd>Special value which signifies inheritance of the default %log
level.</dd></dl>
- Log levels are classes, not numbers. Each log level class has a \c value member which gives
+ Log levels are classes, not numbers. Each %log level class has a \c value member which gives
that levels numeric priority. The larger the number, the more important the message is.
- \implementation The log levels need to be classes since areas and streams are classes: Since
- log arguments (stream, area and level) may appear in any order and number, it is much
+ \implementation The %log levels need to be classes since areas and streams are classes: Since
+ %log arguments (stream, area and level) may appear in any order and number, it is much
simpler to parse them if they are all of the same type.
*/
- ///\ingroup loglevels
///\{
/** \brief Log level VERBOSE
/** \defgroup logging Logging commands
- The logging library provides several commands to create log messages. All these macro commands
+ The logging library provides several commands to create %log messages. All these macro commands
take a variable number of arguments. Since this is not supported in a usable way by the C++
preprocessor, the arguments are encoded into a <a
href="http://www.boost.org/libs/preprocessor/doc/index.html">Boost.Preprocessor</a> like
SENF_LOG( (senf::log::Debug)(senf::log::NOTICE)(FroblizerArea)("The log message") );
\endcode
- The argument is comprised of a sequence of parameters and the log message itself. The parameters
- are
- \li the <em>log stream</em>,
- \li the <em>log area</em>,
- \li the <em>log level</em>.
+ The argument is comprised of a sequence of parameters and the %log message itself.
+ The parameters are
+ - the <em>%log stream</em>,
+ - the <em>%log area</em>,
+ - the <em>%log level</em>.
- These parameters are optional and may be specified <i>in arbitrary order</i> (with the log
+ These parameters are optional and may be specified <i>in arbitrary order</i> (with the %log
message always being the last sequence element) and even multiple times in the parameter
sequence. If some argument type occurs multiple times, the last occurrence wins. If any one of
the parameters is not specified, it's current default value will be used.
The logging library defines the global defaults for stream, area and level to be \c
senf::log::Debug, senf::log::DefaultArea, and senf::log::NONE respectively.
- The log level senf::log::NONE is special. If the log level is set to this value, the log level
+ The %log level senf::log::NONE is special. If the %log level is set to this value, the %log level
will be set from the stream provided default value.
All these parameters must be <em>compile time constants</em> (they are all types, so it's
- difficult form them to be something else).
+ difficult for them to be something else).
\section logging_aliases Aliases
To further simplify logging commands, aliases may be defined within any scope. An alias is an
- arbitrary collection of log parameters:
+ arbitrary collection of %log parameters:
\code
SENF_LOG_DEF_ALIAS( VerboseDebug, (senf::log::Debug)(senf::log::VERBOSE) );
\endcode
- Within log statements, aliases may be used like normal parameters. They will be substituted for
+ Within %log statements, aliases may be used like normal parameters. They will be substituted for
the parameter sequence they represent:
\code
SENF_LOG( (VerboseDebug)("Debug message") )
The target may process in any arbitrary way: reformat, writing it into an SQL DB, whatever
can be envisioned. However, there is one important limitation: The \c v_write call must not
- block. So for more complex scenarios, additional measures must be taken (e.g. writing a log
+ block. So for more complex scenarios, additional measures must be taken (e.g. writing a %log
backend daemon which receives the messages via UDP and processes them). Of course, in rare
cases messages might be lost but this cannot be avoided.
Of course, this only works with objects which explicitly declare, that they take an optional
senf::NoThrow_t type aprameter.
-
*/
namespace senf {
There is only a single value for this type: \ref senf::nothrow which is the value to pass
wherever an (optional) senf::NoThrow_t parameter is requested.
- \see \ref utils_tags
\ingroup utils_tags
*/
enum NoThrow_t { nothrow };
There is only a single value for this type: \ref senf::noinit which is the value to pass
wherever an (optional) senf::NoInit_t parameter is requested.
- \see \ref utils_tags
\ingroup utils_tags
*/
enum NoInit_t { noinit };
projects / senf.git / commitdiff