From ec688b4723a041044226358bcd4dd6e2da39da49 Mon Sep 17 00:00:00 2001 From: Luca Muscariello Date: Thu, 23 Feb 2017 17:01:02 +0100 Subject: Initial commit: cframework. Longbow and Libparc Change-Id: I90378dbd30da6033b20fb1f829b3b822cf366c59 Signed-off-by: Luca Muscariello --- libparc/parc/memory/parc_BufferPool.h | 344 ++++++++++++++++++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 libparc/parc/memory/parc_BufferPool.h (limited to 'libparc/parc/memory/parc_BufferPool.h') diff --git a/libparc/parc/memory/parc_BufferPool.h b/libparc/parc/memory/parc_BufferPool.h new file mode 100644 index 00000000..33028920 --- /dev/null +++ b/libparc/parc/memory/parc_BufferPool.h @@ -0,0 +1,344 @@ +/* + * Copyright (c) 2017 Cisco and/or its affiliates. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at: + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @file parc_BufferPool.h + * @ingroup memory + * @brief A simple pool of uniformly sized PARCBuffer instances. + * + * The client uses `parcBufferPool_GetInstance` to obtain instances which are placed attempted to be placed + * into the pool when the `PARCBuffer_Release` function is called. + * The pool has a maxmimum number of instances that it will cache. + * + */ +#ifndef PARCLibrary_parc_BufferPool +#define PARCLibrary_parc_BufferPool +#include + +#include + +parcObject_Declare(PARCBufferPool); + +/** + * Increase the number of references to a `PARCBufferPool` instance. + * + * Note that new `PARCBufferPool` is not created, + * only that the given `PARCBufferPool` reference count is incremented. + * Discard the reference by invoking `parcBufferPool_Release`. + * + * @param [in] instance A pointer to a valid PARCBufferPool instance. + * + * @return The same value as the parameter @p instance. + * + * Example: + * @code + * { + * PARCBufferPool *a = parcBufferPool_Create(5, 10); + * + * PARCBufferPool *b = parcBufferPool_Acquire(a); + * + * parcBufferPool_Release(&a); + * parcBufferPool_Release(&b); + * } + * @endcode + */ +PARCBufferPool *parcBufferPool_Acquire(const PARCBufferPool *instance); + +#ifdef PARCLibrary_DISABLE_VALIDATION +# define parcBufferPool_OptionalAssertValid(_instance_) +#else +# define parcBufferPool_OptionalAssertValid(_instance_) parcBufferPool_AssertValid(_instance_) +#endif + +/** + * Assert that the given `PARCBufferPool` instance is valid. + * + * @param [in] instance A pointer to a valid PARCBufferPool instance. + * + * Example: + * @code + * { + * PARCBufferPool *a = parcBufferPool_Create(5, 10); + * + * parcBufferPool_AssertValid(a); + * + * parcBufferPool_Release(&a); + * } + * @endcode + */ +void parcBufferPool_AssertValid(const PARCBufferPool *instance); + +/** + * Create an instance of PARCBufferPool containing instances of `PARCBuffer`. + * + * This function is equivalent to invoking + * @code + * PARCBufferPool *a = parcBufferPool_CreateExtending(&parcObject_DescriptorName(PARCBuffer), 5, 10); + * @endcode + * + * The value of @p limit is the maximum number of instances that the pool will cache, + * and @p bufferSize is the size of the `PARCBuffer` instances cached. + * + * @return non-NULL A pointer to a valid PARCBufferPool instance. + * @return NULL An error occurred. + * + * Example: + * @code + * { + * PARCBufferPool *a = parcBufferPool_Create(5, 10); + * + * parcBufferPool_Release(&a); + * } + * @endcode + */ +PARCBufferPool *parcBufferPool_Create(size_t limit, size_t bufferSize); + +/** + * Create an instance of PARCBufferPool containing instances of object specified by the given `PARCObjectDescriptor`. + * + * The value of @p limit is the maximum number of instances that the pool will cache, + * and @p bufferSize is the size of the `PARCBuffer` instances cached. + * + * This function creates a PARCBufferPool that creates and manages instances of PARCBuffer which may have been extended. + * + * @return non-NULL A pointer to a valid PARCBufferPool instance. + * @return NULL An error occurred. + * + * Example: + * @code + * { + * PARCBufferPool *a = parcBufferPool_CreateExtending(&parcObject_DescriptorName(MyPARCBuffer), 5, 10); + * + * parcBufferPool_Release(&a); + * } + * @endcode + */ +PARCBufferPool *parcBufferPool_CreateExtending(const PARCObjectDescriptor *originalDescriptor, size_t limit, size_t bufferSize); + +/** + * Print a human readable representation of the given `PARCBufferPool`. + * + * @param [in] instance A pointer to a valid PARCBufferPool instance. + * @param [in] indentation The indentation level to use for printing. + * + * Example: + * @code + * { + * PARCBufferPool *a = parcBufferPool_Create(5, 10); + * + * parcBufferPool_Display(a, 0); + * + * parcBufferPool_Release(&a); + * } + * @endcode + */ +void parcBufferPool_Display(const PARCBufferPool *instance, int indentation); + +/** + * Determine if an instance of `PARCBufferPool` is valid. + * + * Valid means the internal state of the type is consistent with its required current or future behaviour. + * This may include the validation of internal instances of types. + * + * @param [in] instance A pointer to a valid PARCBufferPool instance. + * + * @return true The instance is valid. + * @return false The instance is not valid. + * + * Example: + * @code + * { + * PARCBufferPool *a = parcBufferPool_Create(5, 10); + * + * if (parcBufferPool_IsValid(a)) { + * printf("Instance is valid.\n"); + * } + * + * parcBufferPool_Release(&a); + * } + * @endcode + * + */ +bool parcBufferPool_IsValid(const PARCBufferPool *instance); + +/** + * Release a previously acquired reference to the given `PARCBufferPool` instance, + * decrementing the reference count for the instance. + * + * The pointer to the instance is set to NULL as a side-effect of this function. + * + * If the invocation causes the last reference to the instance to be released, + * the instance is deallocated and the instance's implementation will perform + * additional cleanup and release other privately held references. + * + * @param [in,out] instancePtr A pointer to a pointer to the instance to release. + * + * Example: + * @code + * { + * PARCBufferPool *a = parcBufferPool_Create(5, 10); + * + * parcBufferPool_Release(&a); + * } + * @endcode + */ +void parcBufferPool_Release(PARCBufferPool **instancePtr); + +/** + * Get an instance of a `PARCBuffer`. + * + * If the PARCBufferPool contains a cached instance, it will be returned. + * Otherwise a new instance will be created. + * + * Any `PARCBuffer` instance which is later released, will be a candidate for caching by the given `PARCBufferPool`. + * + * @param [in] bufferPool A pointer to a valid PARCBufferPool instance. + * + * @return non-NULL A pointer to a valid `PARCBuffer`. + * @return NULL An error occurred. + * + * Example: + * @code + * { + * + * PARCBufferPool *pool = parcBufferPool_Create(5, 10); + * ... + * + * parcBufferPool_Release(&pool); + * } + * @endcode + */ +PARCBuffer *parcBufferPool_GetInstance(PARCBufferPool *bufferPool); + +/** + * Set the largest number of buffers the pool will cache. + * + * If the new limit is less than the current limit, and the current pool size is greater than the new limit, + * the number of buffers the pool will cache will decay as they are obtained and released from the pool during use. + * + * @param [in] bufferPool A pointer to a valid PARCBufferPool instance. + * @param [in] limit the largest number of buffers the pool will cache. + * + * @return The previous value of the largest number of buffers the pool cached. + * + * Example: + * @code + * { + * + * PARCBufferPool *pool = parcBufferPool_Create(5, 10); + * ... + * + * size_t limit = parcBufferPool_SetLimit(pool, 3); + * + * parcBufferPool_Release(&pool); + * } + * @endcode + */ +size_t parcBufferPool_SetLimit(PARCBufferPool *bufferPool, size_t limit); + +/** + * Get the largest number of buffers the pool will cache. + * + * @param [in] bufferPool A pointer to a valid PARCBufferPool instance. + * + * @return The value of the largest number of buffers the pool will cache. + * + * Example: + * @code + * { + * + * PARCBufferPool *pool = parcBufferPool_Create(5, 10); + * ... + * + * size_t limit = parcBufferPool_GetLimit(pool); + * + * parcBufferPool_Release(&pool); + * } + * @endcode + */ +size_t parcBufferPool_GetLimit(const PARCBufferPool *bufferPool); + +/** + * Get the current number of buffers the pool has cached. + * + * The value is always greater than or equal to 0 and less than or equal to the limit. + * + * @param [in] bufferPool A pointer to a valid PARCBufferPool instance. + * + * @return the largest number of buffers the pool has ever cached. + * + * Example: + * @code + * { + * PARCBufferPool *pool = parcBufferPool_Create(5, 10); + * ... + * + * size_t poolSize = parcBufferPool_GetCurrentPoolSize(pool); + * + * parcBufferPool_Release(&pool); + * } + * @endcode + */ +size_t parcBufferPool_GetCurrentPoolSize(const PARCBufferPool *bufferPool); + +/** + * Get the largest number of buffers the pool has ever cached. + * + * The value is always greater than or equal to 0 and less than or equal to the limit. + * + * @param [in] bufferPool A pointer to a valid PARCBufferPool instance. + * + * @return the largest number of buffers the pool has ever cached. + * + * Example: + * @code + * { + * PARCBufferPool *pool = parcBufferPool_Create(5, 10); + * ... + * + * size_t allTimeHigh = parcBufferPool_GetLargestPoolSize(pool); + * + * parcBufferPool_Release(&pool); + * } + * @endcode + */ +size_t parcBufferPool_GetLargestPoolSize(const PARCBufferPool *bufferPool); + +/** + * Forcibly drain the PARCBufferPool of an excess (more than the pool's limit) `PARCBuffer` instances. + * + * The number of PARCBuffer instances can exceed the PARCBufferPool's limit if `parcBufferPool_SetLimit` is used to set the limit + * to less than Pool's current pool size. + * + * @param [in] bufferPool A pointer to a valid PARCBufferPool instance. + * + * @return the largest number of buffers released from the Pool's cache. + * + * Example: + * @code + * { + * + * PARCBufferPool *pool = parcBufferPool_Create(5, 10); + * ... + * + * size_t limit = parcBufferPool_SetLimit(pool, 3); + * size_t drained = parcBufferPool_Drain(pool); + * + * parcBufferPool_Release(&pool); + * } + * @endcode + */ +size_t parcBufferPool_Drain(PARCBufferPool *bufferPool); +#endif -- cgit 1.2.3-korg