From d133133122e11e5d29a829d6fe6a771cdcc80a59 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Tue, 26 Sep 2017 13:08:49 -0600 Subject: [PATCH] Update documentation in VectorMemory and derived classes. --- include/deal.II/lac/vector_memory.h | 78 ++++++++++++++++++++++++++--- 1 file changed, 72 insertions(+), 6 deletions(-) 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); -- 2.39.5