# Miscellaneous

This page documents library components that don't really fit in anywhere else. They all basically follow the same conventions as the rest of the library. So to get a pipe for example you would need to write something like typedef dlib::pipe::kernel_1a pipe_type; and from then on make your pipes like pipe_type my_pipe(pipe_size);.

Objects
bit_stream
byte_orderer
std_allocator
memory_manager
memory_manager_global
memory_manager_stateless
sync_extension
timer
timeout
member_function_pointer
bound_function_pointer
error
pipe
copy_functor
logger
uint64
uint32
uint16
uint8
Global Functions
deserialize
serialize
zero_extend_cast
Testing
dlib_testing_suite
zero_extend_cast
dlib/uintn.h
dlib/uintn.h
This is a global function that performs a zero extending cast from one integral type to another integral type.
uint32
dlib/uintn.h
dlib/uintn.h
This is just a typedef for a 32 bit unsigned integer.
uint8
dlib/uintn.h
dlib/uintn.h
This is just a typedef for an 8 bit unsigned integer.
uint16
dlib/uintn.h
dlib/uintn.h
This is just a typedef for a 16 bit unsigned integer.
std_allocator
dlib/std_allocator.h
dlib/std_allocator.h
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.

std_allocator_ex.cpp.html
uint64
dlib/uintn.h
dlib/uintn.h
This is just a typedef for a 64 bit unsigned integer.
copy_functor
dlib/algs.h
dlib/algs.h
This is a templated function object that makes copies of something.
logger
dlib/logger.h
dlib/logger/logger_kernel_abstract.h
This component is a logging output stream in the style of the log4j logger available for Java. Note that unlike most other objects in this library there is only one implementation. Thus, to create instances of the logger you would simply write logger my_logger("some_name");.
logger_ex.cpp.html
logger_ex_2.cpp.html
pipe_ex.cpp.html
extra_logger_headers
dlib/logger/extra_logger_headers.h
This extension contains additional logger headers you may chose to use instead of the default one.
config_file
dlib/logger/logger_config_file.h
This extension provides the configure_loggers_from_file() function which reads a configuration file from disk that sets up all your loggers.
error
dlib/error.h
dlib/error.h
This is the base exception class from which all exceptions in this library inherit.
pipe
dlib/pipe.h
dlib/pipe/pipe_kernel_abstract.h
This is a first in first out queue with a fixed maximum size containing items of type T. It is suitable for passing objects between threads.
pipe_ex.cpp.html
pipe_ex_2.cpp.html
pipe_kernel_1
dlib/pipe/pipe_kernel_1.h
This implementation is done using a circular buffer in the obvious way. See the source for details.
kernel_1a
is a typedef for pipe_kernel_1
bound_function_pointer
dlib/bound_function_pointer.h
dlib/bound_function_pointer/bound_function_pointer_kernel_abstract.h
This object represents a function with all its arguments bound to specific objects.
bound_function_pointer_kernel_1
dlib/bound_function_pointer/bound_function_pointer_kernel_1.h
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.
kernel_1a
is a typedef for bound_function_pointer_kernel_1
member_function_pointer
dlib/member_function_pointer.h
dlib/member_function_pointer/member_function_pointer_kernel_abstract.h
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.
member_function_pointer_ex.cpp.html
member_function_pointer_kernel_1
dlib/member_function_pointer/member_function_pointer_kernel_1.h
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.
kernel_1a
is a typedef for member_function_pointer_kernel_1
bit_stream
dlib/bit_stream.h
dlib/bit_stream/bit_stream_kernel_abstract.h
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
bit_stream_kernel_1
dlib/bit_stream/bit_stream_kernel_1.h
This implementation is done by buffering single bits in the obvious way.
kernel_1a
is a typedef for bit_stream_kernel_1
bit_stream_multi
dlib/bit_stream/bit_stream_multi_abstract.h
This extension gives a bit_stream object the ability to read/write multiple bits at a time.
bit_stream_multi_1
dlib/bit_stream/bit_stream_multi_1.h
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
byte_orderer
dlib/byte_orderer.h
dlib/byte_orderer/byte_orderer_kernel_abstract.h
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.
byte_orderer_kernel_1
dlib/byte_orderer/byte_orderer_kernel_1.h
This implementation is done in the obvious way.
kernel_1a
is a typedef for byte_orderer_kernel_1
memory_manager_stateless
dlib/memory_manager_stateless.h
dlib/memory_manager_stateless/memory_manager_stateless_kernel_abstract.h
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.
memory_manager_stateless_kernel_1
dlib/memory_manager_stateless/memory_manager_stateless_kernel_1.h
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
dlib/memory_manager_stateless/memory_manager_stateless_kernel_2.h
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
memory_manager_global
dlib/memory_manager_global.h
dlib/memory_manager_global/memory_manager_global_kernel_abstract.h
This object represents some kind of global memory manager or memory pool.
memory_manager_global_kernel_1
dlib/memory_manager_global/memory_manager_global_kernel_1.h
This is implemented in the obvious way. See the code for details.
kernel_1a
is a typedef for memory_manager_global_kernel_1
memory_manager
dlib/memory_manager.h
dlib/memory_manager/memory_manager_kernel_abstract.h
This object represents a memory pool.
memory_manager_kernel_1
dlib/memory_manager/memory_manager_kernel_1.h
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
dlib/memory_manager/memory_manager_kernel_2.h
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
dlib/memory_manager/memory_manager_kernel_3.h
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
sync_extension
dlib/sync_extension.h
dlib/sync_extension/sync_extension_kernel_abstract.h

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.

sync_extension_kernel_1
dlib/sync_extension/sync_extension_kernel_1.h
This is implemented using a rmutex and rsignaler in the obvious way.
kernel_1a
is a typedef for sync_extension_kernel_1
timeout
dlib/timeout.h
dlib/timeout/timeout_kernel_abstract.h
This object provides a simple way to implement a timeout.
timeout_kernel_1
dlib/timeout/timeout_kernel_1.h
This is implemented in the obvious way using virtual functions and templates.
kernel_1a
is a typedef for timeout_kernel_1
timer
dlib/timer.h
dlib/timer/timer_kernel_abstract.h
This object represents a timer that will call a given member function repeatedly at regular intervals.
timer_ex.cpp.html
timer_kernel_1
dlib/timer/timer_kernel_1.h
This is implemented in the obvious way.
kernel_1a
is a typedef for timer_kernel_1
timer_kernel_2
dlib/timer/timer_kernel_2.h
This implementation 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 much more efficient than timer_kernel_1.
kernel_2a
is a typedef for timer_kernel_2
deserialize
dlib/serialize.h
dlib/serialize.h
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::complex, dlib::bigint, dlib::uint64, C style arrays, and dlib::vector objects are serializable.
serialize
dlib/serialize.h
dlib/serialize.h
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::complex, dlib::bigint, dlib::uint64, C style arrays, and dlib::vector objects are serializable.
dlib_testing_suite

This library comes with a command line driven regression test suite. All the testing code is located in the dlib/test 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.