UtiLite: UtiLite

Introduction

UtiLite is a simple library to create small cross-platform applications using threads, events-based communication and a powerful logger. The first three sections show the core classes of the library, then last sections show some useful functions added through time.

UtiLite provides a utility application called uResourceGenerator to generate resources to include in an executable. For example:

 $ ./uresourcegenerator DatabaseSchema.sql

This will generate a HEX file "DatabaseSchema_sql.h" which can be included in source files. Data of the file is global and can be accessed by the generated const char * DATABASESCHEMA_SQL.

 #include "DatabaseSchema_sql.h"
 ...
 std::string hex = DATABASESCHEMA_SQL;
 // Assuming there are only ASCII characters, we can directly convert to a string:
 std::string schema = uHex2Str(hex);
 // For binary data:
 std::vector<char> bytes = uHex2Bytes(hex);

A generated FindUtiLite.cmake is also provided for easy linking with the library.

ULogger

The ULogger can be used anywhere in the application to log messages (formated like a printf). The logger can be set (ULogger::setType()) to print in a file or in the console (with colors depending on the severity). Convenient macros are given, working like a printf(), as UDEBUG(), UINFO(), UWARN(), UERROR(), UFATAL(), UASSERT(). Small example:

 ...
 UINFO("A simple message with number %d", 42);
 UDEBUG("A debug message");
 ...

This will print: [Severity] (Time) File:Line:Function() "The message"

 [ INFO] (2010-09-25 18:08:20) main.cpp:18::main() A simple message with number 42
 [DEBUG] (2010-09-25 18:08:20) main.cpp:18::main() A debug message

UEventsManager, UEventsHandler, UEvent

The events-based communication framework helps to communicate between objects/threads. The UEventsManager is a singleton with which we can post events anywhere in the application by calling UEventsManager::post(). All UEventsHandler will then receive the event with their protected function UEventsHandler::handleEvent(). Handlers are added to UEventsManager by calling UEventsManager::addHandler(). The UEvent provides an abstract class to implement any event implementations. The only requirement is that the event must implements UEvent::getClassName() to know the event's type.

 ...
 MyHandler handler; // MyHandler is an implementation of UEventsHandler
 UEventsManager::addHandler(&handler);
 UEventsManager::post(new MyEvent()); // MyEvent is an implementation of UEvent
 // The UEventsHandler::handleEvent() of "handler" will then be called by the UEventsManager's events dispatching thread.
 ...

Look at the full example in page of UEventsHandler on how communication works with threads (UThread).

UThread, UMutex, USemaphore

The multi-threading framework use a UThread as an abstract class to implement a thread in object-style. Reimplement UThread::mainLoop() then call UThread::start() to start the main loop of the thread. Threads can be joined by calling UThread::join() and killed by calling UThread::kill(). Classes UMutex and USemaphore provide blocking mechanisms to protect data between threads.

 ...
 MyThread t; // MyThread is an implementation of UThread
 t.start();
 t.join(); // Wait the thread to finish
 ...

UTimer

A useful class to compute processing time:

UDirectory, UFile

For files and directories manipulations :

Convenient use of STL

The library provides some simple wrappers of the STL like:

uUniqueKeys() to get unique keys from a std::multimap,
uKeys() to get all keys of a std::multimap or std::map,
uValues() to get all values of a std::multimap or std::map,
uValue() to get the value of a key (with a default argument if the key is not found),
uTake() to take the value of a key (with a default argument if the key is not found),
uIteratorAt() to get iterator at a specified position in a std::list,
uValueAt() to get value at a specified position in a std::list,
uContains() to know if a key/value exists in a std::multimap, std::map, std::list,
uInsert() to insert a value in a std::map and overwriting the value if the key already exists,
uListToVector(),
uVectorToList(),
uAppend() to append a list to another list,
uIndexOf() to get index of a value in a std::list,
uSplit() to split a string into a std::list of strings on the specified separator.

Basic mathematic operations

A library of basic array manipulations:

Conversion

A library of convenient functions to convert some data into another like:

UProcessInfo

This class can be used to get the process memory usage: UProcessInfo::getMemoryUsage().

Qt Widgets (libutilite_qt.so : OPTIONAL)

If Qt is found on the system, the UtiLite Qt library (libutilite_qt.so, libutilite_qt.dll) with useful widgets is built. Use class UPlot to create a plot like MATLAB, and incrementally add new values like a scope. USpectrogram is used to show audio frequency frames.

Audio stuff (libutilite_audio.so : OPTIONAL)

If FMOD is found on the system, the UtiLite audio library is built (libutilite_audio.so, libutilite_audio.dll). It is a wrapper of FMOD methods with a convenient interface to extract audio frames.

UAudioCapture,
UAudioCaptureFile,
UAudioCaptureMic,
UAudioCaptureFFT,
UAudioPlayer,
UAudioPlayerTone,
UWav,
UMp3Encoder (only if Lame is also found on the system).

OpenCV stuff (libutilite_cv.so : OPTIONAL)

If OpenCV is found on the system, the UtiLite cv library is built (libutilite_cv.so, libutilite_cv.dll). It provides image capture classes used to read from a webcam, a video file or a directory of images. If UtiLite is also built with Qt, a convenient function uCvMat2QImage() can be used to convert a cv::Mat image to a QImage.

UVideoCapture,
UImageFolderCapture,
UColorTable,
uTest(), (only if Qt is also found on the system).