/* Copyright (c) V-Nova International Limited 2024-2025. All rights reserved.
 * This software is licensed under the BSD-3-Clause-Clear License by V-Nova Limited.
 * No patent licenses are granted under this license. For enquiries about patent licenses,
 * please contact legal@v-nova.com.
 * The LCEVCdec software is a stand-alone project and is NOT A CONTRIBUTION to any other project.
 * If the software is incorporated into another project, THE TERMS OF THE BSD-3-CLAUSE-CLEAR LICENSE
 * AND THE ADDITIONAL LICENSING INFORMATION CONTAINED IN THIS FILE MUST BE MAINTAINED, AND THE
 * SOFTWARE DOES NOT AND MUST NOT ADOPT THE LICENSE OF THE INCORPORATING PROJECT. However, the
 * software may be incorporated into a project under a compatible license provided the requirements
 * of the BSD-3-Clause-Clear license are respected, and V-Nova Limited remains
 * licensor of the software ONLY UNDER the BSD-3-Clause-Clear license (not the compatible license).
 * ANY ONWARD DISTRIBUTION, WHETHER STAND-ALONE OR AS PART OF ANY OTHER PROJECT, REMAINS SUBJECT TO
 * THE EXCLUSION OF PATENT LICENSES PROVISION OF THE BSD-3-CLAUSE-CLEAR LICENSE. */

#ifndef VN_LCEVC_COMMON_RECYCLING_ALLOCATOR_H
#define VN_LCEVC_COMMON_RECYCLING_ALLOCATOR_H

#include <LCEVC/common/memory.h>
#include <LCEVC/common/vector.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C"
{
#endif

/*! @file
 * @brief A memory allocator adapted that keeps the last few freed blocks, and recycles them
 * when a matching size is requested.
 *
 * This is used within LCEVCdec for image buffer allocations (pictures, upscale, and temporal) where
 * a small cycle of exactly the same (large) size are used repeatedly whist the configuration does
 * not change. By keeping a small cache of these blocks, this avoids churning the system allocator.
 */

typedef struct ldcMemoryRecyclingAllocator ldcMemoryRecyclingAllocator;

/*! Create a new allocator with a recycle cache size.
 *
 * @param[out]      recyclingAllocator      The allocator to be initialized.
 * @param[in]       parentAllocator         The underlying allocator to allocate blocks from.
 * @param[in]       size                    Number of blocks to keep for recycling
 *
 * @return          A pointer to an allocator - as passed in via `recyclingAllocator
 */
LdcMemoryAllocator* ldcRecyclingAllocatorInitialize(ldcMemoryRecyclingAllocator* recyclingAllocator,
                                                    LdcMemoryAllocator* parentAllocator, uint32_t size);

/*! Destroy a previously initialized recycling arena.
 */
void ldcRecyclingAllocatorDestroy(ldcMemoryRecyclingAllocator* recyclingAllocator);

// Allocator definition and inline fast paths
//
#include "detail/recycling_allocator.h"

#ifdef __cplusplus
}
#endif

#endif // VN_LCEVC_COMMON_RECYCLING_ALLOCATOR_H
