[top]bit_stream
This object represents a middle man between a user and the iostream classes that allows single
bits to be read/written easily from/to the iostream classes
Implementations:bit_stream_kernel_1:
This implementation is done by buffering single bits in the obvious way.
kernel_1a | is a typedef for bit_stream_kernel_1 |
kernel_1a_c |
is a typedef for kernel_1a that checks its preconditions.
|
Extensions to bit_stream
bit_stream_multiThis extension gives a bit_stream object the ability to read/write multiple bits at a time.
More Details...Implementations:bit_stream_multi_1:
This implementation is done by calling the read/write functions in the bit_stream kernel.multi_1a | is a typedef for bit_stream_kernel_1 extended by bit_stream_multi_1 |
multi_1a_c |
is a typedef for multi_1a that checks its preconditions.
|
[top]bound_function_pointer
This object represents a function with all its arguments bound to specific objects.
This implementation is done using type erasure and placement new. This
means that it never allocates memory on the heap and instead stores everything
on the stack.
[top]byte_orderer
This object provides a simple type safe mechanism to convert data
to and from network and host byte orders. I.e. to convert things
between big and little endian byte ordering.
[top]console_progress_indicator
This object is a tool for reporting how long a task will take
to complete.
[top]copy_functor
This is a templated function object that makes copies of something.
[top]database
This object is a C++ wrapper around a SQLite database connection
handle and therefore represents a
SQLite database file.
Note that this wrapper is targeted at SQLite Version 3. To use it
you must make sure you link your application with SQLite. However,
if you use CMake and dlib's default CMakeLists.txt file then it will get setup
automatically. This is assuming sqlite3 is properly installed on your system.
On ubuntu you can get it by installing the libsqlite3-dev package. Or you can always
download the SQLite source
and compile it straight into your application (download the amalgamation).
C++ Example Programs:
sqlite_ex.cpp [top]default_memory_manager
This is a memory manager object which simply calls new and delete directly (i.e.
it doesn't really do anything). It is the default memory manager used by most
of the objects in dlib.
[top]deserialize
This is actually a set of overloaded functions which provide the ability to restore an object's state
from an input stream. Currently all dlib container classes, non pointer C++ intrinsics, std::string,
std::vector, std::map, std::set, std::complex, dlib::bigint, dlib::uint64, dlib::int64, C style arrays, and dlib::vector objects are serializable.
You can also use serialize() and deserialize() to read/write Google protocol buffer objects. However,
note that dlib::serialize() writes additional delimiting bytes at the start of each protocol buffer message.
We do this because Google protocol buffers are not
self-delimiting
on their own. This means that you can't write more than one protocol buffer object to an output stream
unless you include some kind of delimiter between the messages.
So dlib takes care of this for you by prefixing each message with its length in bytes. In particular,
the number of bytes is encoded as a 32bit little endian integer.
[top]dlib_testing_suite
This library comes with a command line driven regression test suite. All the testing code
is located in the dlib/test folder. If you want to build it and test the library on your
system you can use the makefile at dlib/test/makefile (you may
have to edit it to make it work on your system) or use the CMake CMakeLists.txt file at
dlib/test/CMakeLists.txt to build it.
What you may find more useful however is the testing framework itself. It uses a fairly simple
and modular design. Each test is contained in its own cpp file and when compiled into the
program it automatically shows up in the list of tests to run. If you want to use the
testing framework all you need to do is add the files dlib/test/tester.h,
dlib/test/tester.cpp, and dlib/test/main.cpp
to your project and then add cpp files that contain your tests (see
dlib/test/example.cpp and
dlib/test/example_args.cpp
for some examples).
From the command line you can choose to run all the installed tests, enable or disable the loggers,
set various logging levels, specify how many times to run the tests, or pick just one or two tests
to run at a time rather than the entire suite.
The output of the program, that is, its return value from main() is the number of
failed tests. So if every test succeeds then it returns 0.
[top]error
This is the base exception class from which all exceptions in this
library inherit.
[top]int16
This is just a typedef for a 16 bit integer.
[top]int32
This is just a typedef for a 32 bit integer.
[top]int64
This is just a typedef for a 64 bit integer.
[top]int8
This is just a typedef for an 8 bit integer.
[top]Java
dlib contains some CMake scripts and related tools that make calling C++ code
from Java easy. If you look in the
dlib/java folder you can find a CMake
project that uses SWIG to build some C++ code and then call it from Java. In
particular, if you run the run_test.sh script it will build and run the code,
calling it from java.
The dlib/java folder also contains some SWIG aware C++ classes that make
interacting with java arrays (e.g. double[]) from C++ efficient and easy.
See the documentation at the top of the java_array.h file for details.
[top]make_mfp
This function is a simple factory for creating
member_function_pointer
objects without needing to know the necessary template arguments for the member_function_pointer.
[top]member_function_pointer
This object represents a member function pointer. It is useful because
instances of this object can be created without needing to know the type
of object whose member function we will be calling.
The implementation of this object is done using type erasure and placement new. This
means that it never allocates memory on the heap and instead stores everything
on the stack.
C++ Example Programs:
member_function_pointer_ex.cpp [top]memory_manager
This object represents a memory pool.
Implementations:memory_manager_kernel_1:
This memory manager implementation allocates objects one at a time when there are
allocation requests. Then when there is a deallocate request the returning object
is placed into a list of free blocks if that list has less than max_pool_size
blocks in it. Subsequent allocation requests will be serviced by drawing from the
free list whenever it isn't empty. Array allocations, on the other hand, are not
managed at all but are passed directly on to new and delete.
When this object's max_pool_size template parameter is set to 0 it simply calls
new and delete directly and doesn't function as a memory pool.
kernel_1a | is a typedef for memory_manager_kernel_1 with a max_pool_size of 0 |
kernel_1b | is a typedef for memory_manager_kernel_1 with a max_pool_size of 10 |
kernel_1c | is a typedef for memory_manager_kernel_1 with a max_pool_size of 100 |
kernel_1d | is a typedef for memory_manager_kernel_1 with a max_pool_size of 1000 |
kernel_1e | is a typedef for memory_manager_kernel_1 with a max_pool_size of 10000 |
kernel_1f | is a typedef for memory_manager_kernel_1 with a max_pool_size of 100000 |
memory_manager_kernel_2:
This memory manager implementation allocates memory in blocks of chunk_size*sizeof(T)
bytes. All the sizeof(T) sub-blocks are kept in a linked list of free memory blocks
and are given out whenever an allocation request occurs. Also, memory is not freed
until this object is destructed.
Also note that array allocations are not managed at all but are passed directly
on to new and delete.
kernel_2a | is a typedef for memory_manager_kernel_2 with a chunk_size of 10 |
kernel_2b | is a typedef for memory_manager_kernel_2 with a chunk_size of 100 |
kernel_2c | is a typedef for memory_manager_kernel_2 with a chunk_size of 1000 |
kernel_2d | is a typedef for memory_manager_kernel_2 with a chunk_size of 10000 |
kernel_2e | is a typedef for memory_manager_kernel_2 with a chunk_size of 100000 |
memory_manager_kernel_3:
This memory manager implementation allocates memory in blocks of chunk_size*sizeof(T)
bytes. All the sizeof(T) sub-blocks are kept in a linked list of free memory blocks
and are given out whenever an allocation request occurs. Note that array allocations
are managed. So this object is just like kernel_2 but it also pools memory from
array allocations (chunk_size has no effect with respect to array allocations, each array
is allocated one at a time).
Also, memory is not freed until this object is destructed.
kernel_3a | is a typedef for memory_manager_kernel_3 with a chunk_size of 10 |
kernel_3b | is a typedef for memory_manager_kernel_3 with a chunk_size of 100 |
kernel_3c | is a typedef for memory_manager_kernel_3 with a chunk_size of 1000 |
kernel_3d | is a typedef for memory_manager_kernel_3 with a chunk_size of 10000 |
kernel_3e | is a typedef for memory_manager_kernel_3 with a chunk_size of 100000 |
[top]memory_manager_global
This object represents some kind of global memory manager or memory pool.
Implementations:memory_manager_global_kernel_1:
This is implemented in the obvious way. See the code for details.
kernel_1a | is a typedef for memory_manager_global_kernel_1 |
[top]memory_manager_stateless
This object represents some kind of stateless memory manager or memory pool.
Stateless means that all instances (instances of the same type that is)
of this object are identical and can be used interchangeably. Note that
implementations are allowed to have some shared global state such as a
global memory pool. This object is also thread safe.
Implementations:memory_manager_stateless_kernel_1:
This implementation just calls new and delete. So it doesn't do anything special.
kernel_1a | is a typedef for memory_manager_stateless_kernel_1 |
memory_manager_stateless_kernel_2:
This implementation uses a global instance of a memory_manager object
guarded by a mutex as its implementation.
kernel_2_1a | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1a |
kernel_2_1b | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1b |
kernel_2_1c | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1c |
kernel_2_1d | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1d |
kernel_2_1e | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1e |
kernel_2_1f | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1f |
kernel_2_2a | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2a |
kernel_2_2b | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2b |
kernel_2_2c | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2c |
kernel_2_2d | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2d |
kernel_2_2e | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2e |
kernel_2_3a | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3a |
kernel_2_3b | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3b |
kernel_2_3c | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3c |
kernel_2_3d | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3d |
kernel_2_3e | is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3e |
[top]pipe
This is a first in first out queue with a fixed maximum size.
It is suitable for passing objects between threads.
This object is optimized for speed, therefore, it uses
global swap() to create a zero-copy method for moving objects
around. For example, on a computer running Ubuntu 12.04 with
a 2.67GHz Intel i7 920 CPU it is possible to pass over 4.4
million std::vector<int> objects a second between two
threads. This is regardless of the number of ints in the std::vector
objects. In particular, this test was done with 100,000
ints in each std::vector.
Finally, note that you can use the pipe as an efficient method to pass
messages between two networked computers by using the bridge.
C++ Example Programs:
pipe_ex.cpp,
pipe_ex_2.cpp,
bridge_ex.cpp [top]serialize
This is actually a set of overloaded functions which provide the ability to save an object's state
to an output stream. Currently all dlib container classes, non pointer C++ intrinsics, std::string,
std::vector, std::map, std::set, std::complex, dlib::bigint, dlib::uint64, dlib::int64, C style arrays, and dlib::vector objects are serializable.
You can also use serialize() and deserialize() to read/write Google protocol buffer objects. However,
note that dlib::serialize() writes additional delimiting bytes at the start of each protocol buffer message.
We do this because Google protocol buffers are not
self-delimiting
on their own. This means that you can't write more than one protocol buffer object to an output stream
unless you include some kind of delimiter between the messages.
So dlib takes care of this for you by prefixing each message with its length in bytes. In particular,
the number of bytes is encoded as a 32bit little endian integer.
[top]statement
This object represents a SQL statement which can be executed
against a
database object. In particular, this object is a
C++ wrapper around a
SQLite prepared statement.
Note that this wrapper is targeted at SQLite Version 3. To use it
you must make sure you link your application with SQLite.
C++ Example Programs:
sqlite_ex.cpp [top]std_allocator
This object is an implementation of an allocator that conforms to the C++ standard
requirements for allocator objects. The M template argument is one of the dlib
memory manager objects and this allocator implementation will do all of its memory allocations
using whatever dlib memory manager you supply.
Thus, using this allocator object you can use any of the dlib memory manager objects with
the containers in the STL or with any other object that requires an STL style allocator object.
C++ Example Programs:
std_allocator_ex.cpp [top]sync_extension
This object represents a general extension to any object. This object gives any object which it extends
an integrated rmutex and rsignaler object. The extended object will
then be able to be treated as if it was also a
rmutex and
rsignaler.
Implementations:sync_extension_kernel_1:
This is implemented using a rmutex
and rsignaler in the obvious way.
kernel_1a | is a typedef for sync_extension_kernel_1 |
[top]timeout
This object provides a simple way to implement a timeout.
[top]timer
This object represents a timer that will call a given member function
repeatedly at regular intervals.
The implementation of this object has a single master thread
that does all the waiting. This master thread creates and
dispatches threads to specific timer objects when they need
to run their action functions. When a timer object isn't
executing its action function then it doesn't have any thread
allocated to it at all. So it is fairly efficient.
C++ Example Programs:
timer_ex.cpp [top]TIME_THIS
This is a macro function for timing blocks of code. Its form is TIME_THIS(whatever you want to time)
It's pretty straight forward. It just prints the time it took to std::cout.
There is another version of this function called TIME_THIS_TO which takes as a parameter an ostream
object to write its output to. Its form is TIME_THIS_TO(what you want to time, the output stream);
[top]timing code blocks
This is a set of set of functions for timing blocks of code. Unlike
TIME_THIS, it can be used to find the cumulative
time spent on a block which is executed multiple times.
[top]uint16
This is just a typedef for a 16 bit unsigned integer.
[top]uint32
This is just a typedef for a 32 bit unsigned integer.
[top]uint64
This is just a typedef for a 64 bit unsigned integer.
[top]uint8
This is just a typedef for an 8 bit unsigned integer.
[top]unserialize
This object effectively allows you to peek at the next serialized
object in an istream. It does this by allowing you to read an object
and then put it back.
[top]vectorstream
This is an iostream object that reads and writes from an in-memory buffer.
It functions very much the same way as the std::stringstream object.
However, while the std::stringstream holds its buffer internally and it can
only be accessed by copying it out, the vectorstream uses an external
std::vector<char> as its buffer. That is, it holds a reference to an
external vector and does not contain any internal buffers of its own.
This object is useful as a slightly more efficient alternative to the
std::stringstream since you can avoid the overhead of copying buffer
contents to and from the stream. This is particularly useful when used as
a source or target for serialization routines.
[top]zero_extend_cast
This is a global function that performs a zero extending cast
from one integral type to another integral type.
Examples: C++