From: Wolfgang Bangerth Date: Tue, 26 Sep 2017 19:08:49 +0000 (-0600) Subject: Update documentation in VectorMemory and derived classes. X-Git-Tag: v9.0.0-rc1~1027^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F5159%2Fhead;p=dealii.git Update documentation in VectorMemory and derived classes. --- diff --git a/include/deal.II/lac/vector_memory.h b/include/deal.II/lac/vector_memory.h index 545b5e3ce0..626fa82faf 100644 --- a/include/deal.II/lac/vector_memory.h +++ b/include/deal.II/lac/vector_memory.h @@ -116,13 +116,35 @@ public: * Return a pointer to a new vector. The number of elements or their * subdivision into blocks (if applicable) is unspecified and users of this * function should reset vectors to their proper size. The same holds for - * the contents of vectors: they are unspecified. + * the contents of vectors: they are unspecified. In other words, + * the place that calls this function will need to resize or reinitialize + * it appropriately. + * + * @warning Just like using new and delete + * explicitly in code invites bugs where memory is leaked (either + * because the corresponding delete is forgotten + * altogether, or because of exception safety issues), using the + * alloc() and free() functions explicitly invites writing code + * that accidentally leaks memory. You should consider using + * the VectorMemory::Pointer class instead, which provides the + * same kind of service that std::unique provides + * for arbitrary memory allocated on the heap. */ virtual VectorType *alloc () = 0; /** * Return a vector and indicate that it is not going to be used any further - * by the instance that called alloc() to get a pointer to it. + * by the place that called alloc() to get a pointer to it. + * + * @warning Just like using new and delete + * explicitly in code invites bugs where memory is leaked (either + * because the corresponding delete is forgotten + * altogether, or because of exception safety issues), using the + * alloc() and free() functions explicitly invites writing code + * that accidentally leaks memory. You should consider using + * the VectorMemory::Pointer class instead, which provides the + * same kind of service that std::unique provides + * for arbitrary memory allocated on the heap. */ virtual void free (const VectorType *const) = 0; @@ -210,10 +232,23 @@ public: * Return a pointer to a new vector. The number of elements or their * subdivision into blocks (if applicable) is unspecified and users of this * function should reset vectors to their proper size. The same holds for - * the contents of vectors: they are unspecified. + * the contents of vectors: they are unspecified. In other words, + * the place that calls this function will need to resize or reinitialize + * it appropriately. * * For the present class, calling this function will allocate a new vector - * on the heap and returning a pointer to it. + * on the heap and returning a pointer to it. Later calling free() then + * returns the memory to the global heap managed by the operating system. + * + * @warning Just like using new and delete + * explicitly in code invites bugs where memory is leaked (either + * because the corresponding delete is forgotten + * altogether, or because of exception safety issues), using the + * alloc() and free() functions explicitly invites writing code + * that accidentally leaks memory. You should consider using + * the VectorMemory::Pointer class instead, which provides the + * same kind of service that std::unique provides + * for arbitrary memory allocated on the heap. */ virtual VectorType *alloc (); @@ -221,9 +256,18 @@ public: * Return a vector and indicate that it is not going to be used any further * by the instance that called alloc() to get a pointer to it. * - * * For the present class, this means that the vector is returned to the * global heap. + * + * @warning Just like using new and delete + * explicitly in code invites bugs where memory is leaked (either + * because the corresponding delete is forgotten + * altogether, or because of exception safety issues), using the + * alloc() and free() functions explicitly invites writing code + * that accidentally leaks memory. You should consider using + * the VectorMemory::Pointer class instead, which provides the + * same kind of service that std::unique provides + * for arbitrary memory allocated on the heap. */ virtual void free (const VectorType *const v); }; @@ -285,7 +329,19 @@ public: * Return a pointer to a new vector. The number of elements or their * subdivision into blocks (if applicable) is unspecified and users of this * function should reset vectors to their proper size. The same holds for - * the contents of vectors: they are unspecified. + * the contents of vectors: they are unspecified. In other words, + * the place that calls this function will need to resize or reinitialize + * it appropriately. + * + * @warning Just like using new and delete + * explicitly in code invites bugs where memory is leaked (either + * because the corresponding delete is forgotten + * altogether, or because of exception safety issues), using the + * alloc() and free() functions explicitly invites writing code + * that accidentally leaks memory. You should consider using + * the VectorMemory::Pointer class instead, which provides the + * same kind of service that std::unique provides + * for arbitrary memory allocated on the heap. */ virtual VectorType *alloc (); @@ -295,6 +351,16 @@ public: * * For the present class, this means retaining the vector for later reuse by * the alloc() method. + * + * @warning Just like using new and delete + * explicitly in code invites bugs where memory is leaked (either + * because the corresponding delete is forgotten + * altogether, or because of exception safety issues), using the + * alloc() and free() functions explicitly invites writing code + * that accidentally leaks memory. You should consider using + * the VectorMemory::Pointer class instead, which provides the + * same kind of service that std::unique provides + * for arbitrary memory allocated on the heap. */ virtual void free (const VectorType *const);