From 537bee9f4c81f0caac7dece67c1dc9c2f7661f43 Mon Sep 17 00:00:00 2001
From: Kevin Bracey <kevin.bracey@arm.com>
Date: Tue, 13 Apr 2021 13:12:39 +0300
Subject: [PATCH] Better document MemoryPool behaviour

Make explicit that `MemoryPool` is a raw allocator, and users need to
take care of object construction and destruction.
---
 rtos/include/rtos/MemoryPool.h | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/rtos/include/rtos/MemoryPool.h b/rtos/include/rtos/MemoryPool.h
index 14903504528..7b3fff623f9 100644
--- a/rtos/include/rtos/MemoryPool.h
+++ b/rtos/include/rtos/MemoryPool.h
@@ -97,6 +97,19 @@ class MemoryPool : private mbed::NonCopyable<MemoryPool<T, pool_sz> > {
     }
 
     /** Allocate a memory block from a memory pool, without blocking.
+
+      This method works like `std::malloc` or `std::allocator<T>::allocate` in that the
+      returned memory block is not initialized. For types with a non-trivial constructor
+      placement new must be used to construct an object in the returned storage.
+
+      Example:
+      @code
+      MyObject *obj = pool.alloc();
+      if (obj) {
+          new (obj) MyObject(1, 2);
+      }
+      @endcode
+
       @return  address of the allocated memory block or nullptr in case of no memory available.
 
       @note You may call this function from ISR context.
@@ -120,6 +133,7 @@ class MemoryPool : private mbed::NonCopyable<MemoryPool<T, pool_sz> > {
     }
 
     /** Allocate a memory block from a memory pool, optionally blocking.
+      @see MemoryPool::try_alloc
       @param   rel_time  timeout value (Kernel::wait_for_u32_forever to wait forever)
       @return  address of the allocated memory block or nullptr in case of no memory available.
 
@@ -149,6 +163,7 @@ class MemoryPool : private mbed::NonCopyable<MemoryPool<T, pool_sz> > {
     }
 
     /** Allocate a memory block from a memory pool, blocking.
+      @see MemoryPool::try_alloc
       @param   abs_time absolute timeout time, referenced to Kernel::Clock.
       @return  address of the allocated memory block or nullptr in case of no memory available.
 
@@ -264,6 +279,17 @@ class MemoryPool : private mbed::NonCopyable<MemoryPool<T, pool_sz> > {
     }
 
     /** Free a memory block.
+
+      This method works like `std::free` or `std::allocator<T>::deallocate` in that any
+      object in the memory is not destroyed. For types with a non-trivial destructor
+      that destructor must be called manually before freeing the memory.
+
+      Example:
+      @code
+      obj->~MyObject();
+      pool.free(obj);
+      @endcode
+
       @param   block  address of the allocated memory block to be freed.
       @return         osOK on successful deallocation, osErrorParameter if given memory block id
                       is nullptr or invalid, or osErrorResource if given memory block is in an