feat(alloc): support capacity limit

1. Add capacity limit.
2. Add an API to retrieve the current available memory size.

#32

docs/Melon Developer Guide.txt

@@ -1299,10 +1299,11 @@ Their definitions can be found in melon/include/mln_types.h.
 
   16) Memory Pool
      The memory pool can help developer use memory more easily.
-     a) mln_alloc_t *mln_alloc_init(mln_alloc_t *parent);
+     a) mln_alloc_t *mln_alloc_init(mln_alloc_t *parent, mln_size_t capacity);
         Initialize a memory pool object.
         'parent' is another memory pool, which means a memory pool can be created by another pool.
         If 'parent' is NULL, memory pool will be created from heap.
+        `capacity` is the capacity limit of the pool. If it is set to `0`, the capacity would be unlimited.
 
      b) void mln_alloc_destroy(mln_alloc_t *pool);
         Destroy a memory pool object and free all memory blocks that it allocated.
@@ -1321,9 +1322,9 @@ Their definitions can be found in melon/include/mln_types.h.
      f) void mln_alloc_free(void *ptr);
         Free a memory block to a memory pool.
 
-     g) mln_alloc_t *mln_alloc_shm_init(mln_size_t size, void *locker, mln_alloc_shm_lock_cb_t lock, mln_alloc_shm_lock_cb_t unlock);
+     g) mln_alloc_t *mln_alloc_shm_init(mln_size_t capacity, void *locker, mln_alloc_shm_lock_cb_t lock, mln_alloc_shm_lock_cb_t unlock);
         Initialize a shared memory pool.
-        `size` - shared memory size
+        `capacity` - shared memory capacity
         `locker` - lock
         `lock` - lock handler
         `unlock` - unlock handler
@@ -1333,6 +1334,18 @@ Their definitions can be found in melon/include/mln_types.h.
         'lock' and 'unlock' will be called only in sub-pool functions.
         So user should lock or unlock by yourself when operate shared memory pool directly.
 
+     h) mln_size_t mln_alloc_available_capacity(mln_alloc_t *pool);
+        Retrieve the current available capacity of the memory pool (if a capacity limit is set for the memory pool).
+        For heap memory pools, when calling `mln_alloc_m`, several memory blocks similar in size to the requested allocation may be
+        pre-allocated. In such cases, the value returned by this function does not include the memory size of these pre-allocated
+        but unused blocks.
+
+        Heap Memory: If the second parameter (`capacity`) in `mln_alloc_init` is not `0`, the function returns the current
+        available memory size of the memory pool (refer to the note above for details). If it is `0`, the function returns
+        `MLN_ALLOC_INFINITE_SIZE`.
+
+        Shared Memory: Returns the total size of all available memory regions in bytes.
+
   17) Chain & Buf
      These two structures do not have interfaces to operate.
      We should set them manually. Just like buf and chain in Nginx.

docs/book/cn/mpool.md

@@ -30,10 +30,10 @@ Melon中，内存池分为两类：
 #### mln_alloc_init
 
 ```c
-mln_alloc_t *mln_alloc_init(mln_alloc_t *parent);
+mln_alloc_t *mln_alloc_init(mln_alloc_t *parent, mln_size_t capacity);
 ```
 
-描述：创建堆内存内存池。参数`parent`是一个内存池实例，该参数为`NULL`时，本函数创建的内存池将从堆中分配内存，若不为`NULL`时，则从`parent`所在池中分配内存。即池结构可级联。
+描述：创建堆内存内存池。参数`parent`是一个内存池实例，该参数为`NULL`时，本函数创建的内存池将从堆中分配内存，若不为`NULL`时，则从`parent`所在池中分配内存。即池结构可级联。`capacity`是用于限制内存池容量的，当它的值为`0`时，表示内存池容量不受限，也就是跟随系统内存容量。
 
 返回值：成功则返回内存池结构指针，否则返回`NULL`
 
@@ -42,14 +42,14 @@ mln_alloc_t *mln_alloc_init(mln_alloc_t *parent);
 #### mln_alloc_shm_init
 
 ```c
-mln_alloc_t *mln_alloc_shm_init(mln_size_t size, void *locker, mln_alloc_shm_lock_cb_t lock, mln_alloc_shm_lock_cb_t unlock);
+mln_alloc_t *mln_alloc_shm_init(mln_size_t capacity, void *locker, mln_alloc_shm_lock_cb_t lock, mln_alloc_shm_lock_cb_t unlock);
 ```
 
 描述：创建共享内存内存池。
 
 参数：
 
-- `size` 本池建立时需要给出池大小`size`（单位字节），一旦创建完毕后则后续无法再扩大。
+- `capacity` 本池建立时需要给出池大小（单位字节），一旦创建完毕后则后续无法再扩大。
 - `locker` 是锁资源结构指针。
 - `lock` 是用于对锁资源加锁的回调函数，该函数参数为锁资源指针。若加锁失败则返回`非0`值。
 - `unlock` 是用于对锁资源解锁的回调函数，该函数参数为锁资源指针。若解锁失败则返回`非0`值。
@@ -126,6 +126,23 @@ void mln_alloc_free(void *ptr);
 
 
 
+#### mln_alloc_available_capacity
+
+```c
+mln_size_t mln_alloc_available_capacity(mln_alloc_t *pool);
+```
+
+描述：获取当前内存池剩余可用容量（如果内存池设置了容量限制）。
+
+注意：对于堆内存池，当调用`mln_alloc_m`时会欲分配若干与申请大小相似的内存块。在这种情况下，本函数返回的数值并不包含这些被预分配且未被使用的块的内存大小。
+
+返回值：
+
+- 堆内存：若在`mln_alloc_init`时第二个参数（`capacity`）不为`0`，则返回当前内存池剩余可用内存大小（详情参考上面注意事项），若为`0`，则返回`M_ALLOC_INFINITE_SIZE`。
+- 共享内存：返回全部可用内存区的字节大小。
+
+
+
 ### 示例
 
 ```c

docs/book/en/mpool.md

@@ -32,10 +32,10 @@ Among them, the shared memory memory pool only allows data to be shared between
 #### mln_alloc_init
 
 ```c
-mln_alloc_t *mln_alloc_init(mln_alloc_t *parent);
+mln_alloc_t *mln_alloc_init(mln_alloc_t *parent, mln_size_t capacity);
 ```
 
-Description: Create a heap memory memory pool. The parameter `parent` is a memory pool instance. When the parameter is `NULL`, the memory pool created by this function will allocate memory from the heap. If it is not `NULL`, it will allocate memory from the pool where `parent` is located. That is, the pool structure can be cascaded.
+Description: Create a heap memory memory pool. The parameter `parent` is a memory pool instance. When the parameter is `NULL`, the memory pool created by this function will allocate memory from the heap. If it is not `NULL`, it will allocate memory from the pool where `parent` is located. That is, the pool structure can be cascaded. `capacity` is used to limit the memory pool's capacity. When its value is `0`, it indicates that the memory pool capacity is unlimited, meaning it follows the system's available memory capacity.
 
 Return value: If successful, return the memory pool structure pointer, otherwise return `NULL`
 
@@ -44,14 +44,14 @@ Return value: If successful, return the memory pool structure pointer, otherwise
 #### mln_alloc_shm_init
     
 ```c
-mln_alloc_t *mln_alloc_shm_init(mln_size_t size, void *locker, mln_alloc_shm_lock_cb_t lock, mln_alloc_shm_lock_cb_t unlock);                  
+mln_alloc_t *mln_alloc_shm_init(mln_size_t capacity, void *locker, mln_alloc_shm_lock_cb_t lock, mln_alloc_shm_lock_cb_t unlock);                  
 ``` 
 
 Description: Create a shared memory memory pool.
 
 Parameters:
 
-- `size` The pool size `size` (in bytes) needs to be given when creating this pool. Once created, it cannot be expanded later.
+- `capacity` The pool size (in bytes) needs to be given when creating this pool. Once created, it cannot be expanded later.
 - `locker` is the lock resource pointer.
 - `lock` is a callback function used to lock the lock resource. The function parameter is the lock resource pointer. If the lock fails, a `non-0` value is returned.
 - `unlock` is a callback function used to unlock the lock resource. The function parameter is the lock resource pointer. If unlocking fails, a `non-0` value is returned.
@@ -128,6 +128,23 @@ Return value: none
 
 
 
+#### mln_alloc_available_capacity
+
+```c
+mln_size_t mln_alloc_available_capacity(mln_alloc_t *pool);
+```
+
+Description: Retrieve the current available capacity of the memory pool (if a capacity limit is set for the memory pool).
+
+Note: For heap memory pools, when calling `mln_alloc_m`, several memory blocks similar in size to the requested allocation may be pre-allocated. In such cases, the value returned by this function does not include the memory size of these pre-allocated but unused blocks.
+
+Return Values:
+
+Heap Memory: If the second parameter (`capacity`) in `mln_alloc_init` is not `0`, the function returns the current available memory size of the memory pool (refer to the note above for details). If it is `0`, the function returns `M_ALLOC_INFINITE_SIZE`.
+Shared Memory: Returns the total size of all available memory regions in bytes.
+
+
+
 ### Example
 
 ```c