<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="stylesheet.xsl"?>

<doc>
   <title>Miscellaneous</title>

   <!-- ************************************************************************* -->

   <body>
      <br/><br/>

         <p>

         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 <tt>typedef dlib::pipe::kernel_1a pipe_type;</tt> and from then on make your pipes like 
         <tt>pipe_type my_pipe(pipe_size);</tt>.  
         </p>

   </body>

   <!-- ************************************************************************* -->

   <menu width="200">
    <top>
      <section>
         <name>Objects</name>
         <item>bit_stream</item> 
         <item>byte_orderer</item>
         <item>std_allocator</item> 
         <item>memory_manager</item> 
         <item>memory_manager_global</item> 
         <item>memory_manager_stateless</item> 
         <item>default_memory_manager</item> 
         <item>sync_extension</item> 
         <item>timer</item> 
         <item>timeout</item> 
         <item>member_function_pointer</item>
         <item>bound_function_pointer</item>
         <item>error</item>
         <item>console_progress_indicator</item>
         <item>pipe</item>
         <item>copy_functor</item>
         <item>logger</item>
         <item nolink="true">
            <name>Fixed_width_integers</name>
            <sub>
               <item>uint64</item>
               <item>uint32</item>
               <item>uint16</item>
               <item>uint8</item>
               <item>int64</item>
               <item>int32</item>
               <item>int16</item>
               <item>int8</item>
            </sub>
         </item>
      </section>
 
      <section>
         <name>Global Functions</name>
         <item>deserialize</item> 
         <item>serialize</item> 
         <item>zero_extend_cast</item> 
      
      </section>

      <section>
         <name>Testing</name>
         <item>dlib_testing_suite</item>
      </section>

    </top>  
   </menu>

   <!-- ************************************************************************* -->
   <!-- ************************************************************************* -->
   <!-- ************************************************************************* -->

   <components>
   
   
   <!-- ************************************************************************* -->
      
      <component>
         <name>zero_extend_cast</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is a global function that performs a zero extending cast
            from one integral type to another integral type.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->
      
      <component>
         <name>uint32</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is just a typedef for a 32 bit unsigned integer.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->
      
      <component>
         <name>uint8</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is just a typedef for an 8 bit unsigned integer.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      
      <component>
         <name>uint16</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is just a typedef for a 16 bit unsigned integer.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>int8</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is just a typedef for an 8 bit integer.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>int16</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is just a typedef for a 16 bit integer.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>int32</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is just a typedef for a 32 bit integer.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>int64</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is just a typedef for a 64 bit integer.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>std_allocator</name>
         <file>dlib/std_allocator.h</file>
         <spec_file>dlib/std_allocator.h</spec_file>
         <description>
                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.   

                  <p>
                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.
                  </p>
         </description>

         <examples>
            <example>std_allocator_ex.cpp.html</example>
         </examples>
         
      </component>
      
   <!-- ************************************************************************* -->
      
      <component>
         <name>uint64</name>
         <file>dlib/uintn.h</file>
         <spec_file link="true">dlib/uintn.h</spec_file>
         <description>
            This is just a typedef for a 64 bit unsigned integer.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->
      
      <component>
         <name>copy_functor</name>
         <file>dlib/algs.h</file>
         <spec_file link="true">dlib/algs.h</spec_file>
         <description>
            This is a templated function object that makes copies of something. 
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>logger</name>
         <file>dlib/logger.h</file>
         <spec_file>dlib/logger/logger_kernel_abstract.h</spec_file>
         <description>
                This component is a logging output stream in the style of the log4j
                logger available for Java.                  
         </description>
         
         <examples>
            <example>logger_ex.cpp.html</example>
            <example>logger_ex_2.cpp.html</example>
            <example>pipe_ex.cpp.html</example>
         </examples>

         <extensions>
            <extension>
               <name>extra_logger_headers</name>
               <spec_file>dlib/logger/extra_logger_headers.h</spec_file>
               <description>This extension contains additional logger headers you may chose to use instead of the
                  default one. </description>
            </extension>
            <extension>
               <name>config_file</name>
               <spec_file>dlib/logger/logger_config_file.h</spec_file>
               <description>This extension provides the configure_loggers_from_file() function
               which reads a configuration file from disk that sets up all your loggers.</description>
            </extension>
         </extensions>              
                                    

      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>error</name>
         <file>dlib/error.h</file>
         <spec_file link="true">dlib/error.h</spec_file>
         <description>
            This is the base exception class from which all exceptions in this 
            library inherit.
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>console_progress_indicator</name>
         <file>dlib/console_progress_indicator.h</file>
         <spec_file link="true">dlib/console_progress_indicator.h</spec_file>
         <description>
               This object is a tool for reporting how long a task will take
               to complete.   
         </description>
         
      </component>
      
   <!-- ************************************************************************* -->

      <component>
         <name>pipe</name>
         <file>dlib/pipe.h</file>
         <spec_file>dlib/pipe/pipe_kernel_abstract.h</spec_file>
         <description>
                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.
         </description>
         
         <examples>
            <example>pipe_ex.cpp.html</example>
            <example>pipe_ex_2.cpp.html</example>
         </examples>

         <implementations>
            <implementation>
               <name>pipe_kernel_1</name>
               <file>dlib/pipe/pipe_kernel_1.h</file>
               <description> 
                  This implementation is done using a circular buffer in the obvious way. See the source for details.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for pipe_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
         </implementations>
                           
                        
      </component>
      
      
   <!-- ************************************************************************* -->
      
      <component checked="true">
         <name>bound_function_pointer</name>
         <file>dlib/bound_function_pointer.h</file>
         <spec_file>dlib/bound_function_pointer/bound_function_pointer_kernel_abstract.h</spec_file>
         <description>
            This object represents a function with all its arguments bound to specific objects. 
         </description>
         
         <implementations>
            <implementation>
               <name>bound_function_pointer_kernel_1</name>
               <file>dlib/bound_function_pointer/bound_function_pointer_kernel_1.h</file>
               <description> 
                  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.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for bound_function_pointer_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
         </implementations>
                           
                        
      </component>
      
      
   <!-- ************************************************************************* -->
      
      <component checked="true">
         <name>member_function_pointer</name>
         <file>dlib/member_function_pointer.h</file>
         <spec_file>dlib/member_function_pointer/member_function_pointer_kernel_abstract.h</spec_file>
         <description>
            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.
         </description>
         
         <examples>
            <example>member_function_pointer_ex.cpp.html</example>
         </examples>

         <implementations>
            <implementation>
               <name>member_function_pointer_kernel_1</name>
               <file>dlib/member_function_pointer/member_function_pointer_kernel_1.h</file>
               <description> 
                  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.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for member_function_pointer_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
         </implementations>
                           
                        
      </component>
      
      
   <!-- ************************************************************************* -->
      
      <component checked="true">
         <name>bit_stream</name>
         <file>dlib/bit_stream.h</file>
         <spec_file>dlib/bit_stream/bit_stream_kernel_abstract.h</spec_file>
         <description>
            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         
         </description>
         
         <implementations>
            <implementation>
               <name>bit_stream_kernel_1</name>
               <file>dlib/bit_stream/bit_stream_kernel_1.h</file>
               <description> 
                  This implementation is done by buffering single bits in the obvious way.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for bit_stream_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
         </implementations>
                     

         <extensions>
            <extension>
               <name>bit_stream_multi</name>
               <spec_file>dlib/bit_stream/bit_stream_multi_abstract.h</spec_file>
               <description>This extension gives a bit_stream object the ability to read/write multiple bits at a time.</description>
               <implementations>
                  <implementation>
                     <name>bit_stream_multi_1</name>
                     <file>dlib/bit_stream/bit_stream_multi_1.h</file>
                     <description>This implementation is done by calling the read/write functions in the bit_stream kernel.</description>
                     <typedefs>
                        <typedef>
                           <name>multi_1a</name>
                           <description>is a typedef for bit_stream_kernel_1 extended by bit_stream_multi_1</description>
                        </typedef>
                     </typedefs>
                  </implementation>
               </implementations>
            </extension>
         </extensions>              
                                    
                        
      </component>
      
   <!-- ************************************************************************* -->
      
      <component>
         <name>byte_orderer</name>
         <file>dlib/byte_orderer.h</file>
         <spec_file>dlib/byte_orderer/byte_orderer_kernel_abstract.h</spec_file>
         <description>
            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.
         </description>
         
         <implementations>
            <implementation>
               <name>byte_orderer_kernel_1</name>
               <file>dlib/byte_orderer/byte_orderer_kernel_1.h</file>
               <description> 
                  This implementation is done in the obvious way.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for byte_orderer_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation>                                  
         </implementations>
                        
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>default_memory_manager</name>
         <file>dlib/algs.h</file>
         <spec_file link="true">dlib/algs.h</spec_file>
         <description>
            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.
         </description>
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>memory_manager_stateless</name>
         <file>dlib/memory_manager_stateless.h</file>
         <spec_file>dlib/memory_manager_stateless/memory_manager_stateless_kernel_abstract.h</spec_file>
         <description>
                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.
         </description>
         
         <implementations>
            <implementation>
               <name>memory_manager_stateless_kernel_1</name>
               <file>dlib/memory_manager_stateless/memory_manager_stateless_kernel_1.h</file>
               <description> 
                  This implementation just calls new and delete.  So it doesn't do anything special.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for memory_manager_stateless_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 

            <implementation>
               <name>memory_manager_stateless_kernel_2</name>
               <file>dlib/memory_manager_stateless/memory_manager_stateless_kernel_2.h</file>
               <description> 
                  This implementation uses a global instance of a <a href="#memory_manager">memory_manager</a> object
                  guarded by a mutex as its implementation.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_2_1a</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1a</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_1b</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1b</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_1c</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1c</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_1d</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1d</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_1e</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1e</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_1f</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_1f</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_2a</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2a</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_2b</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2b</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_2c</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2c</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_2d</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2d</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_2e</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_2e</description>
                  </typedef>

                  <typedef>
                     <name>kernel_2_3a</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3a</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_3b</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3b</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_3c</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3c</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_3d</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3d</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2_3e</name>
                     <description>is a typedef for memory_manager_stateless_kernel_2 that uses memory_manager_3e</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
         </implementations>
                        
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>memory_manager_global</name>
         <file>dlib/memory_manager_global.h</file>
         <spec_file>dlib/memory_manager_global/memory_manager_global_kernel_abstract.h</spec_file>
         <description>
                This object represents some kind of global memory manager or memory pool.  
         </description>
         
         <implementations>
            <implementation>
               <name>memory_manager_global_kernel_1</name>
               <file>dlib/memory_manager_global/memory_manager_global_kernel_1.h</file>
               <description> 
                  This is implemented in the obvious way.  See the code for details.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for memory_manager_global_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
         </implementations>
                        
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>memory_manager</name>
         <file>dlib/memory_manager.h</file>
         <spec_file>dlib/memory_manager/memory_manager_kernel_abstract.h</spec_file>
         <description>
                This object represents a memory pool. 
         </description>
         
         <implementations>
            <implementation>
               <name>memory_manager_kernel_1</name>
               <file>dlib/memory_manager/memory_manager_kernel_1.h</file>
               <description> 
                  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.
               <p>
                  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.  
               </p>
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for memory_manager_kernel_1 with a max_pool_size of 0</description>
                  </typedef>
                  <typedef>
                     <name>kernel_1b</name>
                     <description>is a typedef for memory_manager_kernel_1 with a max_pool_size of 10</description>
                  </typedef>
                  <typedef>
                     <name>kernel_1c</name>
                     <description>is a typedef for memory_manager_kernel_1 with a max_pool_size of 100</description>
                  </typedef>
                  <typedef>
                     <name>kernel_1d</name>
                     <description>is a typedef for memory_manager_kernel_1 with a max_pool_size of 1000</description>
                  </typedef>
                  <typedef>
                     <name>kernel_1e</name>
                     <description>is a typedef for memory_manager_kernel_1 with a max_pool_size of 10000</description>
                  </typedef>
                  <typedef>
                     <name>kernel_1f</name>
                     <description>is a typedef for memory_manager_kernel_1 with a max_pool_size of 100000</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
            <implementation>
               <name>memory_manager_kernel_2</name>
               <file>dlib/memory_manager/memory_manager_kernel_2.h</file>
               <description> 
                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.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_2a</name>
                     <description>is a typedef for memory_manager_kernel_2 with a chunk_size of 10</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2b</name>
                     <description>is a typedef for memory_manager_kernel_2 with a chunk_size of 100</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2c</name>
                     <description>is a typedef for memory_manager_kernel_2 with a chunk_size of 1000</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2d</name>
                     <description>is a typedef for memory_manager_kernel_2 with a chunk_size of 10000</description>
                  </typedef>
                  <typedef>
                     <name>kernel_2e</name>
                     <description>is a typedef for memory_manager_kernel_2 with a chunk_size of 100000</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
            <implementation>
               <name>memory_manager_kernel_3</name>
               <file>dlib/memory_manager/memory_manager_kernel_3.h</file>
               <description> 
                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.  
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_3a</name>
                     <description>is a typedef for memory_manager_kernel_3 with a chunk_size of 10</description>
                  </typedef>
                  <typedef>
                     <name>kernel_3b</name>
                     <description>is a typedef for memory_manager_kernel_3 with a chunk_size of 100</description>
                  </typedef>
                  <typedef>
                     <name>kernel_3c</name>
                     <description>is a typedef for memory_manager_kernel_3 with a chunk_size of 1000</description>
                  </typedef>
                  <typedef>
                     <name>kernel_3d</name>
                     <description>is a typedef for memory_manager_kernel_3 with a chunk_size of 10000</description>
                  </typedef>
                  <typedef>
                     <name>kernel_3e</name>
                     <description>is a typedef for memory_manager_kernel_3 with a chunk_size of 100000</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
         </implementations>
                        
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>sync_extension</name>
         <file>dlib/sync_extension.h</file>
         <spec_file>dlib/sync_extension/sync_extension_kernel_abstract.h</spec_file>
         <description>
            
                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 <a href="dlib/threads/rmutex_extension_abstract.h.html#rmutex">rmutex</a> and 
                <a href="dlib/threads/rsignaler_extension_abstract.h.html#rsignaler">rsignaler</a>.
   
         </description>
         
         <implementations>
            <implementation>
               <name>sync_extension_kernel_1</name>
               <file>dlib/sync_extension/sync_extension_kernel_1.h</file>
               <description> 
                  This is implemented using a <a href="dlib/threads/rmutex_extension_abstract.h.html#rmutex">rmutex</a> 
                  and <a href="dlib/threads/rsignaler_extension_abstract.h.html#rsignaler">rsignaler</a> in the obvious way.  
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for sync_extension_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
         </implementations>
                        
      </component>
            
      
   <!-- ************************************************************************* -->
      
      <component>
         <name>timeout</name>
         <file>dlib/timeout.h</file>
         <spec_file>dlib/timeout/timeout_kernel_abstract.h</spec_file>
         <description>
            This object provides a simple way to implement a timeout. 
         </description>
    
         <implementations>
            <implementation>
               <name>timeout_kernel_1</name>
               <file>dlib/timeout/timeout_kernel_1.h</file>
               <description> 
                  This is implemented in the obvious way using virtual functions and templates.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for timeout_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
         </implementations>
                        
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>timer</name>
         <file>dlib/timer.h</file>
         <spec_file>dlib/timer/timer_kernel_abstract.h</spec_file>
         <description>
                This object represents a timer that will call a given member function 
                repeatedly at regular intervals.
         </description>
    
         <examples>
            <example>timer_ex.cpp.html</example>
         </examples>
         
         <implementations>
            <implementation>
               <name>timer_kernel_1</name>
               <file>dlib/timer/timer_kernel_1.h</file>
               <description> 
                  This is implemented in the obvious way.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_1a</name>
                     <description>is a typedef for timer_kernel_1</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
            <implementation>
               <name>timer_kernel_2</name>
               <file>dlib/timer/timer_kernel_2.h</file>
               <description> 
                  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.
               </description> 
    
               <typedefs>
                  <typedef>
                     <name>kernel_2a</name>
                     <description>is a typedef for timer_kernel_2</description>
                  </typedef>
               </typedefs>                
               
            </implementation> 
                     
         </implementations>
                        
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>deserialize</name>
         <file>dlib/serialize.h</file>
         <spec_file>dlib/serialize.h</spec_file>
         <description>
            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, dlib::int64, C style arrays, and dlib::vector objects are serializable.  
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
      <component>
         <name>serialize</name>
         <file>dlib/serialize.h</file>
         <spec_file>dlib/serialize.h</spec_file>
         <description>
            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, dlib::int64, C style arrays, and dlib::vector objects are serializable.   
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->

      <component>
         <name>dlib_testing_suite</name>
         <description>
      <p>
      This library comes with a command line driven regression test suite.  All the testing code
      is located in the <chm>dlib/test</chm><web><a href="dlib/test">dlib/test</a></web> folder.  If you want to build it and test the library on your 
      system you can use the makefile at <a href="dlib/test/makefile">dlib/test/makefile</a> (you may
      have to edit it to make it work on your system) or use the CMake CMakeLists.txt file at 
      <a href="dlib/test/CMakeLists.txt.html">dlib/test/CMakeLists.txt</a> to build it.  
      </p>
      <p>
         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 <a href="dlib/test/tester.h.html">dlib/test/tester.h</a>,
         <a href="dlib/test/tester.cpp.html">dlib/test/tester.cpp</a>, and <a href="dlib/test/main.cpp.html">dlib/test/main.cpp</a>
         to your project and then add cpp files that contain your tests (see 
         <a href="dlib/test/example.cpp.html">dlib/test/example.cpp</a> and 
         <a href="dlib/test/example_args.cpp.html">dlib/test/example_args.cpp</a> 
         for some examples).
      </p>
      <p>
         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.
      </p>
         </description>
                                 
      </component>
            
   <!-- ************************************************************************* -->
      
   </components>

   <!-- ************************************************************************* -->


</doc>
