From e6cd9187dca2d35190045d4cef4cdc95f0292b2d Mon Sep 17 00:00:00 2001 From: wolf Date: Mon, 27 Nov 2000 14:32:42 +0000 Subject: [PATCH] Add documentation, separate implementation from declarations. git-svn-id: https://svn.dealii.org/trunk@3506 0785d39b-7218-0410-832d-ea1e28bc413d --- .../base/include/base/memory_consumption.h | 667 +++++++++++------- 1 file changed, 399 insertions(+), 268 deletions(-) diff --git a/deal.II/base/include/base/memory_consumption.h b/deal.II/base/include/base/memory_consumption.h index 2eb08c9d22..b139bfec09 100644 --- a/deal.II/base/include/base/memory_consumption.h +++ b/deal.II/base/include/base/memory_consumption.h @@ -21,7 +21,62 @@ /** - * Basic types, vectors of basic types, strings, vectors of composed types + * This namespace provides functions helping to determine the amount + * of memory used by objects. The goal is not necessarily to give the + * amount of memory used up to the last bit (what is the memory used + * by an STL @p{map<>} object?), but rather to aid in the search for + * memory bottlenecks. + * + * The functions in this namespace work basically by reducing each + * object to its basics as far as they are known from this place. They + * do not attempt to know what goes on in each object, if they are not + * basic types (such as @p{int} or @p{double}) or STL containers (such + * as @p{vectors}). The method goes as follows: if the object with + * which a @p{memory_consumption} function from this namespace is an + * atomic type, the return its size by applying the @p{sizeof} + * operator to it. If this is not the case, then try to reduce it to + * more basic types. + * + * For example, if it is a C-style array or a standard C++ @p{vector}, + * then sum up the sizes of the array elements by calling + * @p{memory_consumption} on each of them. This way, we can also + * reduce objects of type @p{vector >} to its atomic + * types, and can thus determine the memory used even if the sizes of + * the elements of the outermost vector differ (e.g. the first + * sub-vector has 3 and the second sub-vector has 10 elements). + * + * There are two exceptions to simply adding up the sizes of the + * subobjects: for C++ @p{vector} objects, we also have to add the + * size of the vector object, i.e. @p{sizeof(vector)}, to the sizes + * of the elements. Secondly, for the most common used vectors, such + * as @p{vector} and @p{vector} we determine the + * size without a loop but rather directly, since we know that the + * sizes of the elements are constant. + * + * Finally, if we cannot reduce a type @p{T} further, because it is + * neither atomic nor a known C++ data type, we call a member function + * @{T::memory_consumption} on it, which we assume to exist. Almost + * all classes in the deal.II library have such a function. This way, + * if we call @p{memory_consumption(v)} on a vector @p{v} of type + * @p{FullMatrix}, we first reduce this to a loop in which we + * call @p{memory_consumption(v[i])}, and because there is no such + * function handling this explicitely, we try to call + * @p{v[i].memory_consumption()}. + * + * + * @sect3{Extending this namespace} + * + * The functions in this namespace and the functionality provided by + * it live on the assumption that there is either a function + * @p{memory_consumption(T)} in this namespace determining the amount + * of memory use by objects of type @p{T}, or that the class @p{T} has + * a function of that name as member function. While the latter is + * true for almost all class in deal.II, we have only implemented the + * first kind of functions for the most common data types, such as + * atomic types, strings, C++ vectors, C-style arrays, and C++ + * pairs. These functions therefore do not cover, for example, C++ + * maps, lists, etc. If you need such functions feel free to implement + * them and send them to us for inclusion. * * @author Wolfgang Bangerth, 2000 */ @@ -32,95 +87,56 @@ namespace MemoryConsumption * in bytes consumed by a @p{bool} * variable. */ - inline - unsigned int memory_consumption (const bool) - { - return sizeof(bool); - }; + unsigned int memory_consumption (const bool); /** * Determine the amount of memory * in bytes consumed by a @p{char} * variable. */ - inline - unsigned int memory_consumption (const char) - { - return sizeof(char); - }; + unsigned int memory_consumption (const char); /** * Determine the amount of memory * in bytes consumed by a * @p{short int} variable. */ - inline - unsigned int memory_consumption (const short int) - { - return sizeof(short int); - }; - + unsigned int memory_consumption (const short int); /** * Determine the amount of memory * in bytes consumed by a * @p{short unsigned int} variable. */ - inline - unsigned int memory_consumption (const short unsigned int) - { - return sizeof(short unsigned int); - }; - - + unsigned int memory_consumption (const short unsigned int); /** * Determine the amount of memory * in bytes consumed by a @p{int} * variable. */ - inline - unsigned int memory_consumption (const int) - { - return sizeof(int); - }; - + unsigned int memory_consumption (const int); /** * Determine the amount of memory * in bytes consumed by a @p{unsigned int} * variable. */ - inline - unsigned int memory_consumption (const unsigned int) - { - return sizeof(unsigned int); - }; - + unsigned int memory_consumption (const unsigned int); /** * Determine the amount of memory * in bytes consumed by a @p{float} * variable. */ - inline - unsigned int memory_consumption (const float) - { - return sizeof(float); - }; - - + unsigned int memory_consumption (const float); /** * Determine the amount of memory * in bytes consumed by a @p{double} * variable. */ - inline - unsigned int memory_consumption (const double) - { - return sizeof(double); - }; + unsigned int memory_consumption (const double); /** * Determine an estimate of the @@ -128,7 +144,7 @@ namespace MemoryConsumption * consumed by a @p{string} * variable. */ - unsigned int memory_consumption (const string &s); + unsigned int memory_consumption (const string &s); /** * Determine an estimate of the @@ -177,244 +193,359 @@ namespace MemoryConsumption * applies for the special case of * vectors of bools. */ - template - unsigned int memory_consumption (const vector &v) - { - unsigned int mem = sizeof(vector); - const unsigned int n = v.size(); - for (unsigned int i=0; i - unsigned int memory_consumption (const T (&v)[N]) - { - unsigned int mem = 0; - for (unsigned int i=0; i &v) - { - return v.capacity() / 8 + sizeof(v); - }; + template + unsigned int memory_consumption (const vector &v); + /** + * Estimate the amount of memory + * (in bytes) occupied by a + * C-style array. Since in this + * library we do not usually + * store simple data elements + * like @p{double}s in such + * arrays (but rather use STL + * @p{vector}s or deal.II + * @p{Vector} objects), we do not + * provide specializations like + * for the @p{vector} arrays, but + * always use the loop over all + * elements. + */ + template + unsigned int memory_consumption (const T (&v)[N]); + + /** + * Specialization of the + * determination of the memory + * consumption of a vector, here + * for a vector of @p{bool}s. + * + * This is a special case, as the + * bools are not stored + * one-by-one, but as a bit + * field. + */ + unsigned int memory_consumption (const vector &v); - /** - * Specialization of the - * determination of the memory - * consumption of a vector, here - * for a vector of @p{int}s. - */ - inline - unsigned int memory_consumption (const vector &v) - { - return (v.capacity() * sizeof(int) + - sizeof(v)); - }; - + /** + * Specialization of the + * determination of the memory + * consumption of a vector, here + * for a vector of @p{int}s. + */ + unsigned int memory_consumption (const vector &v); - /** - * Specialization of the - * determination of the memory - * consumption of a vector, here - * for a vector of @p{double}s. - */ - inline - unsigned int memory_consumption (const vector &v) - { - return (v.capacity() * sizeof(double) + - sizeof(v)); - }; + /** + * Specialization of the + * determination of the memory + * consumption of a vector, here + * for a vector of @p{double}s. + */ + unsigned int memory_consumption (const vector &v); + /** + * Specialization of the + * determination of the memory + * consumption of a vector, here + * for a vector of @p{float}s. + */ + unsigned int memory_consumption (const vector &v); - /** - * Specialization of the - * determination of the memory - * consumption of a vector, here - * for a vector of @p{float}s. - */ - inline - unsigned int memory_consumption (const vector &v) - { - return (v.capacity() * sizeof(float) + - sizeof(v)); - }; + /** + * Specialization of the + * determination of the memory + * consumption of a vector, here + * for a vector of @p{char}s. + */ + unsigned int memory_consumption (const vector &v); + /** + * Specialization of the + * determination of the memory + * consumption of a vector, here + * for a vector of @p{unsigned char}s. + */ + unsigned int memory_consumption (const vector &v); - /** - * Specialization of the - * determination of the memory - * consumption of a vector, here - * for a vector of @p{char}s. - */ - inline - unsigned int memory_consumption (const vector &v) - { - return (v.capacity() * sizeof(char) + - sizeof(v)); - }; + /** + * Specialization of the + * determination of the memory + * consumption of a vector, here + * for a vector of pointers. + */ + template + unsigned int memory_consumption (const vector &v); + + /** + * Determine an estimate of the + * amount of memory in bytes + * consumed by a pair of values. + */ + template + unsigned int memory_consumption (const pair &p); + /** + * Return the amount of memory + * used by a pointer. Make sure + * that you are really interested + * in this, and not the amount of + * memory required by the object + * pointed to. + */ + template + unsigned int memory_consumption (const T * const); + /** + * Return the amount of memory + * used by a pointer. Make sure + * that you are really interested + * in this, and not the amount of + * memory required by the object + * pointed to. + * + * This function is the same as + * above, but for non-const + * pointers + */ + template + unsigned int memory_consumption (T * const); + + /** + * Return the amount of memory + * used by a void pointer. Make + * sure that you are really + * interested in this, and not + * the amount of memory required + * by the object pointed to. + * + * Note that we needed this + * function since @p{void} is no + * type and a @p{void*} is thus + * not caught by the general + * @p{T*} template function + * above. + */ + unsigned int memory_consumption (void * const); + - /** - * Specialization of the - * determination of the memory - * consumption of a vector, here - * for a vector of @p{unsigned char}s. - */ - inline - unsigned int memory_consumption (const vector &v) - { - return (v.capacity() * sizeof(unsigned char) + - sizeof(v)); - }; + /** + * For all other types which are + * not explicitely listed: try if + * there is a member function + * called + * @p{memory_consumption}. If + * this is not the case, then the + * compiler will in any case + * complain that this last exit + * does not work. + */ + template + unsigned int memory_consumption (const T &t); +} + +// now comes the implementation of these functions +namespace MemoryConsumption +{ + inline + unsigned int memory_consumption (const bool) + { + return sizeof(bool); + }; + + + + inline + unsigned int memory_consumption (const char) + { + return sizeof(char); + }; + + + + inline + unsigned int memory_consumption (const short int) + { + return sizeof(short int); + }; + + + + inline + unsigned int memory_consumption (const short unsigned int) + { + return sizeof(short unsigned int); + }; + + + + inline + unsigned int memory_consumption (const int) + { + return sizeof(int); + }; + + + + inline + unsigned int memory_consumption (const unsigned int) + { + return sizeof(unsigned int); + }; + + + + inline + unsigned int memory_consumption (const float) + { + return sizeof(float); + }; + + + + inline + unsigned int memory_consumption (const double) + { + return sizeof(double); + }; + + + + template + unsigned int memory_consumption (const vector &v) + { + unsigned int mem = sizeof(vector); + const unsigned int n = v.size(); + for (unsigned int i=0; i + unsigned int memory_consumption (const T (&v)[N]) + { + unsigned int mem = 0; + for (unsigned int i=0; i &v) + { + return v.capacity() / 8 + sizeof(v); + }; + + + + inline + unsigned int memory_consumption (const vector &v) + { + return (v.capacity() * sizeof(int) + + sizeof(v)); + }; + + + + inline + unsigned int memory_consumption (const vector &v) + { + return (v.capacity() * sizeof(double) + + sizeof(v)); + }; - /** - * Specialization of the - * determination of the memory - * consumption of a vector, here - * for a vector of pointers. - */ - template - inline - unsigned int memory_consumption (const vector &v) - { - return (v.capacity() * sizeof(T *) + - sizeof(v)); - }; - /** - * Determine an estimate of the - * amount of memory in bytes - * consumed by a pair of values. - */ - template - inline - unsigned int memory_consumption (const pair &p) - { - return (memory_consumption(p.first) + - memory_consumption(p.second)); - }; + inline + unsigned int memory_consumption (const vector &v) + { + return (v.capacity() * sizeof(float) + + sizeof(v)); + }; + - /** - * Return the amount of memory - * used by a pointer. Make sure - * that you are really interested - * in this, and not the amount of - * memory required by the object - * pointed to. - */ - template - inline - unsigned int - memory_consumption (const T * const) - { - return sizeof(T*); - }; - - - - /** - * Return the amount of memory - * used by a pointer. Make sure - * that you are really interested - * in this, and not the amount of - * memory required by the object - * pointed to. - * - * This function is the same as - * above, but for non-const - * pointers - */ - template - inline - unsigned int - memory_consumption (T * const) - { - return sizeof(T*); - }; - - - - /** - * Return the amount of memory - * used by a void pointer. Make - * sure that you are really - * interested in this, and not - * the amount of memory required - * by the object pointed to. - * - * Note that we needed this - * function since @p{void} is no - * type and a @p{void*} is thus - * not caught by the general - * @p{T*} template function - * above. - */ - inline - unsigned int - memory_consumption (void * const) - { - return sizeof(void*); - }; + + inline + unsigned int memory_consumption (const vector &v) + { + return (v.capacity() * sizeof(char) + + sizeof(v)); + }; + + + + inline + unsigned int memory_consumption (const vector &v) + { + return (v.capacity() * sizeof(unsigned char) + + sizeof(v)); + }; + + + + template + inline + unsigned int memory_consumption (const vector &v) + { + return (v.capacity() * sizeof(T *) + + sizeof(v)); + }; + + + + template + inline + unsigned int memory_consumption (const pair &p) + { + return (memory_consumption(p.first) + + memory_consumption(p.second)); + }; + + + + template + inline + unsigned int + memory_consumption (const T * const) + { + return sizeof(T*); + }; + + + + template + inline + unsigned int + memory_consumption (T * const) + { + return sizeof(T*); + }; + + + + inline + unsigned int + memory_consumption (void * const) + { + return sizeof(void*); + }; - /** - * For all other types which are - * not explicitely listed: try if - * there is a member function - * called - * @p{memory_consumption}. If - * this is not the case, then the - * compiler will in any case - * complain that this last exit - * does not work. - */ - template - inline - unsigned int - memory_consumption (const T &t) - { - return t.memory_consumption(); - }; + + template + inline + unsigned int + memory_consumption (const T &t) + { + return t.memory_consumption(); + }; } -- 2.39.5