Merge "C2BufferQueueBlockPool: Add more documentation" into main

 *

 * If a specific HGBP is configured, the HGBP acts as an allocator for creating graphic blocks.

 *

 * TODO: add more ducumentation(graphic block life-cycle, waitable object and workaounds)

 *

 * HGBP/IGBP and the BlockPool

 *

 * GraphicBuffer(s) from BufferQueue(IGBP/IGBC) are based on slot id.

 * A created GraphicBuffer occupies a slot(so the GraphicBuffer has a slot-id).

 * A GraphicBuffer is produced and consumed and recyled based on the slot-id

 * w.r.t. BufferQueue.

 *

 * HGBP::dequeueBuffer() returns a slot id where the slot has an available GraphicBuffer.

 * If it is necessary, HGBP allocates a new GraphicBuffer to the slot and indicates

 * that a new buffer is allocated as return flag.

 * To retrieve the GraphicBuffer, HGBP::requestBuffer() along with the slot id

 * is required. In order to save HGBP remote calls, the blockpool caches the

 * allocated GraphicBuffer(s) along with the slot information.

 *

 * The blockpool provides C2GraphicBlock upon \fetchGraphicBlock().

 * The C2GraphicBlock has a native handle, which is extracted from a GraphicBuffer

 * and then cloned for independent life-cycle with the GraphicBuffer. The GraphicBuffer

 * is allocated by HGBP::dequeueBuffer() and retrieved by HGBP::requestBuffer()

 * if there is a HGBP configured.

 *

 *

 * Life-cycle of C2GraphicBlock

 *

 * The decoder HAL writes a decoded frame into C2GraphicBlock. Upon

 * completion, the component sends the block to the client in the remote process

 * (i.e. to MediaCodec). The remote process renders the frame into the output surface

 * via IGBP::queueBuffer() (Note: this is not hidlized.).

 *

 * If the decoder HAL destroys the C2GraphicBlock without transferring to the

 * client, the destroy request goes to the BlockPool. Then

 * the BlockPool free the associated GraphicBuffer from a slot to

 * HGBP in order to recycle via HGBP::cancelBuffer().

 *

 *

 * Clearing the Cache(GraphicBuffer)

 *

 * When the output surface is switched to a new surface, The GraphicBuffers from

 * the old surface is either migrated or cleared.

 *

 * The GraphicBuffer(s) still in use are migrated to a new surface during

 * configuration via HGBP::attachBuffer(). The GraphicBuffer(s) not in use are

 * cleared from the cache inside the BlockPool.

 *

 * When the surface is switched to a null surface, all the

 * GraphicBuffers in the cache are cleared.

 *

 *

 * Workaround w.r.t. b/322731059 (Deferring cleaning the cache)

 *

 * Some vendor devices have issues with graphic buffer lifecycle management,

 * where the graphic buffers get released even when the cloned native handles

 * in the remote process are not closed yet. This issue led to rare crashes

 * for those devices when the cache is cleared early.

 *

 * We workarounded the crash by deferring the cleaning of the cache.

 * The workaround is not enabled by default, and can be enabled via a

 * system property as shown below:

 *

 *        'debug.codec2.bqpool_dealloc_after_stop' = 1

 *

 * Configuring the debug flag will call \::setDeferDeallocationAfterStop()

 * after the blockpool creation. This will enable the deferring.

 *

 * After enabling the deferring, clearing the GraphicBuffer is delayed until

 *  1) \::clearDeferredBlocks() is called.

 *        Typically after HAL processes stop() request.

 *  2) Or a new ::fetchGraphicBlock() is called.

 *

 *  Since the deferring will delay the deallocation, the deferring will result

 *  in more memory consumption during the brief period.

 */

class C2BufferQueueBlockPool : public C2BlockPool {

public: