/*!
\addtogroup group_alloc_format Format Of The Overview Of Allocated Memory
\ingroup group_overview
*/
/*!
\page page_alloc_format
\ingroup group_alloc_format

<hr><h2>Detailed Description</h2>

The format of the \link group_overview Overview Of Allocated Memory \endlink can be altered
and/or the content can be filtered by passing an object of type libcwd::alloc_filter_ct 
to the function \ref list_allocations_on.  This object is constructed out of
\c alloc_format_t constants which act as bits in a bit-mask.

It is possible to include the time at which each allocation
was made by passing the bit \c show_time.  This
will prepend "hours:minutes:seconds.microseconds" to the output:

\code
04:07:16.712874 malloc    0x8078648          alloctag.cc:65   void*; (sz = 220)
\endcode

It is also possible to show the full path of the location file
by passing the bit \c show_path.  This makes the output
look like:

\code
malloc    0x8078648 /home/carlo/c++/libcwd/testsuite/libcwd.tst/alloctag.cc:65   void*; (sz = 220)
\endcode

It is also possible to show the name of the object file (shared library or
executable name) to which the allocation belongs by using the bit \c show_objectfile.
The name of the corresponding object file is prepended to the location:

\code
malloc    0x8078648 tst_alloctag_shared:         alloctag.cc:65   void*; (sz = 220)
\endcode

Finally, it is possible to show the mangled function name where the allocation
was done by using the bit \c show_function.
The mangled name of the corresponding function is prepended to the location:

\code
new[]     0x8199158 _Z7new1000j           module.cc:47   char[1000]; (sz = 1000)
\endcode

The flags can be combined with the bit-wise OR operator.

<b>Example:</b>

\code
#ifdef CWDEBUG
libcwd::alloc_filter_ct filter(libcwd::show_time | libcwd::show_path);
#endif

Debug( list_allocations_on(libcw_do, filter) );
\endcode

<b>Filtering</b>

There are four criteria on which can be filtered: the time at which an allocation was
made, the shared library that an allocation belongs too, the name of the source file
from which an allocation was made and whether or not an AllocTag was used for the
allocation.

It is possible to give a time interval of the allocations that should be shown.
For each of the limits (start and end) one can use the constant struct timeval libcwd::alloc_filter_ct::no_time_limit
to indicate that there is no limit required.

It is also possible to specify a list of wildcard masks (of the kind where a '*' matches anything) that
will be matched against the names of the shared libraries, hiding the allocations that belong to the
libraries whose name match.

It is also possible to specify a list of wildcard masks (of the kind where a '*' matches anything) that
will be matched against the names of the source file from which the allocation was done, only showing the
allocations that whose name match.

Finally, it is also possible to hide all allocations except when one of the \link group_annotation AllocTag \endlink macros was used.
Please note that using this option makes it hard to see whether or not your application has any
memory leaks in the case the leak has no <CODE>AllocTag</CODE> added.

<b>Examples:</b>

In order to show all allocations that were done one hour or more ago, one could do:

\code
#ifdef CWDEBUG
libcwd::alloc_filter_ct filter(libcwd::show_time);
struct timeval end;
gettimeofday(&end, 0);
end.tv_sec -= 3600;
filter.set_time_interval(libcwd::alloc_filter_ct::no_time_limit, end);
#endif

Debug( list_allocations_on(libcw_do, filter) );
\endcode

In order to hide all allocations that belong to any shared library (only
leaving the allocations that belong to the executable), one could do:

\code
#ifdef CWDEBUG
libcwd::alloc_filter_ct filter(libcwd::show_objectfile);
std::vector<std::string> masks;
masks.push_back("lib*");
filter.hide_objectfiles_matching(masks);
#endif

Debug( list_allocations_on(libcw_do, filter) );
\endcode

In order to hide allocations done from a specific function in a specific
shared library, one could do:

\code
#ifdef CWDEBUG
libcwd::alloc_filter_ct filter(libcwd::show_objectfile|libcwd::show_function);
std::vector<std::pair<std::string, std::string> > hide_list;
hide_list.push_back(std::pair<std::string, std::string>("libdl.so.2", "_dlerror_run"));
hide_list.push_back(std::pair<std::string, std::string>("libstdc++.so.6", "__cxa_get_globals"));
filter.hide_functions_matching(hide_list);
#endif

Debug( list_allocations_on(libcw_do, filter) );
\endcode

Note that also here it is allowed to use masks, for both the object file as well as the mangled function name.

In order to hide all allocations that are done from inside the header files
of installed libraries (like the STL), one could do:

\code
#ifdef CWDEBUG
libcwd::alloc_filter_ct filter(libcwd::show_path);
std::vector<std::string> masks;
masks.push_back("/usr/include/*.h");
filter.hide_sourcefiles_matching(masks);
#endif

Debug( list_allocations_on(libcw_do, filter) );
\endcode

In order to hide everything except those allocations that one explicitely
added an \link group_annotation AllocTag \endlink for, one could do:

\code
#ifdef CWDEBUG
libcwd::alloc_filter_ct filter;
filter.hide_untagged_allocations();
#endif

Debug( list_allocations_on(libcw_do, filter) );
\endcode

*/
