From patchwork Tue Sep 19 19:56:54 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andreas Rheinhardt X-Patchwork-Id: 43813 Delivered-To: ffmpegpatchwork2@gmail.com Received: by 2002:a05:6a20:a886:b0:149:dfde:5c0a with SMTP id ca6csp185284pzb; Tue, 19 Sep 2023 12:56:51 -0700 (PDT) X-Google-Smtp-Source: AGHT+IEvCpnbGQeHeXFTKcxv+s+Ex5YjvI7vkOxPm9r2sFohHFduAdSCuwElHDaUnQ9TvCCZdop5 X-Received: by 2002:a5d:408d:0:b0:321:6de5:68b4 with SMTP id o13-20020a5d408d000000b003216de568b4mr497140wrp.52.1695153411644; Tue, 19 Sep 2023 12:56:51 -0700 (PDT) Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id qt16-20020a170906ecf000b009945340230esi10274707ejb.174.2023.09.19.12.56.51; Tue, 19 Sep 2023 12:56:51 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@outlook.com header.s=selector1 header.b=BU9z2pCe; arc=fail (body hash mismatch); spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org; dmarc=fail (p=NONE sp=QUARANTINE dis=NONE) header.from=outlook.com Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 5266A68C945; Tue, 19 Sep 2023 22:56:46 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from EUR05-AM6-obe.outbound.protection.outlook.com (mail-am6eur05olkn2055.outbound.protection.outlook.com [40.92.91.55]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 42B9168C915 for ; Tue, 19 Sep 2023 22:56:39 +0300 (EEST) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=AWyA3zHD4mBuDIdL0YFd3Nz7zlVwR/p7h/PNcP/KwDx4wk34fYYJvGg8WyPfiveOXD0cuS+13vhTUcTGYUu8Us53QiIaizFkwBSSka08RsWsnjg3cLjGpZ04PZx5lpbryIOJJnTovDcG+SDdcDp2j/whOezKO096fiuslc64tyT2zKgk6VFwouPsmBBIOhjVjHyqEhSN37ky3TAhdGEP38xJlW+SLXMaPJxh1aMcO90ZfRu54adrnyXYWnsueuarXulounNa78F1JkvRLboyV492zEupTOcbpPDLyPfFQ9/GWLtVSdS4nJaOdR+joZW0/s4gazUq8ebN5x1tYfyt/w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=zgHJkda654S7RKxkb9g0N/ImBExnzD/cvLMebeC+Sgs=; b=Rwqh3eGu0OrwrEDdGf/X+atoL0T9OTx+so8j3HQMbh2BNjc9yBM/ieMunFiWTYCcX9Xq6GtSBHb+09MzD4AnkzvGGPSpu/UCVfsBNvGo3qCeAaYGm861gF0PJu3frpRSFR9VfRHmXhYV9irmjIRBVALXa1ssYKZpTD0+O91guKRyY6nyF5fka/d1OcFz6hHk7ATOCxMtf5NjBxciZGTuP0F4ZNlGD/XAAE+nTOCyrCQXy7YU0PBjulXW1UFfE/yn6HQGxRkcZqOg7bS4w84NguC77QeFCuZrpPJXJKp9g9zJjvncwO4JhAbx9hMmeOBE3F0T03Dk519BD0UEGj06fQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=none; dmarc=none; dkim=none; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=outlook.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=zgHJkda654S7RKxkb9g0N/ImBExnzD/cvLMebeC+Sgs=; b=BU9z2pCeURGh/S2SSAygOCZRm0Gh0bmmWornckXScOs4X6MAsdgijk2sEcKaxDmpkrRXVeUIK1V03CzJDXeUZYZMnbS32DZRck62ZH8ZIaW6zKF7CKqtfjkWPq34L5eZEdkB2IA70MqO7QVZryVTFWYOPOq+CeAfy3JJge3NuntY+BB91n0EJYsji97wTXGplhDxp231w0Ua3u/7sjqINb7UiR1t6wIuQeuY/Qck9SCOykuneLalawlP/7P1U+NhfgF3ZYKtun1phVMWE6OBEddSUjUSbX5YEmgRMlxlEIFH4aF9B5C6SI4as73u66cgounI3x2DpgNYkSNpT33M1A== Received: from AS8P250MB0744.EURP250.PROD.OUTLOOK.COM (2603:10a6:20b:541::14) by DU2P250MB0303.EURP250.PROD.OUTLOOK.COM (2603:10a6:10:27c::7) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6792.26; Tue, 19 Sep 2023 19:56:37 +0000 Received: from AS8P250MB0744.EURP250.PROD.OUTLOOK.COM ([fe80::5e01:aea5:d3a8:cafa]) by AS8P250MB0744.EURP250.PROD.OUTLOOK.COM ([fe80::5e01:aea5:d3a8:cafa%3]) with mapi id 15.20.6792.026; Tue, 19 Sep 2023 19:56:37 +0000 From: Andreas Rheinhardt To: ffmpeg-devel@ffmpeg.org Date: Tue, 19 Sep 2023 21:56:54 +0200 Message-ID: X-Mailer: git-send-email 2.34.1 In-Reply-To: References: X-TMN: [4eeTTegnlsLpO+h+yPJuYyLy5fOX5Ii9] X-ClientProxiedBy: ZR0P278CA0086.CHEP278.PROD.OUTLOOK.COM (2603:10a6:910:22::19) To AS8P250MB0744.EURP250.PROD.OUTLOOK.COM (2603:10a6:20b:541::14) X-Microsoft-Original-Message-ID: <20230919195734.1005750-2-andreas.rheinhardt@outlook.com> MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: AS8P250MB0744:EE_|DU2P250MB0303:EE_ X-MS-Office365-Filtering-Correlation-Id: 7e07cf1e-8647-4a9c-0b79-08dbb94a8889 X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: r9Nhk7Fi3nBEDHXmV3QU9aOZh8wyRz2vlVYgqcrjgc9i0uFIkowi006jUSYQSOI/8x42X2nV5QZsA9tTqdiW9hGMjIU088FCyaQJcVzY7gbMoEdWrcgtJxbC7fgx3qGYVmzWfvDcXdnP2pT/keuiMJTz6tEpNyKmEwWoc+htNGvbR1bs35793g3Zb2XmAF8JgWHMgvRORNUGOqh9R67K+DNWspSOLmywKbUL5IQZwQQ3jBfhijDmguBFZIldf6Z+m8sCNKuPOoRySAfD/b4XunAX5QEbZ8ERfBT8Ejnpz3S5XOgVGO3XZZb8c+7XlOsjfmgsrx6QLguK6Rf2eh1gRy8BYjA3SLhtQRSbcSRM2pY6KJoeQnwBi40MQUelUXpxTY3b1wKxApMkG9fDPK+p9tvsugcYZqsuywaXTnv6TGOEnUyGO0Z00Kx8Wxk/5kkMS+/PG26YL72VXBaHWrnjhXD1/CvgI75ECxA2iEJkLfdtToFuto2koRbdyxUgoj0j0L5gm6ByxevIRhPliEX0KvFsGZ3xAq8FKPeCipSuCLjKBr0ey7dWi9DGDH7HQLHvS2z1PbhBaYfo95NHgj/Tp8HB3raZPxk8u7z2d5EgnPprWdNul2+XjPytalXdQwf2 X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: 09LRYORoyfigL10bhX4HgwkCD2XCbi4XoY2ldcBb1ug9TWmLIi3rFWO8SdjoyNZJo3E8jfxzoO5YnSlpTKnV8lVf8KKNsxfuHeb7VRcu2h1nqqy7vYHR0sGrC/21lf11JGP6uxkV3dmUlmxMqTixxLx+avU3zr9uXRS3ALh0k3530LuLRfGjdtB7Jtp16MwBfe9kUkYiwKlhbNshxpJQCotIxHqm10jaq6GcFD2bNNFSyO50EOZieeDkyWfoUN+lx1HxMDunfrnWPXxSvtpckxV6mnF2YGNq4YLwC3M0gR0YWIpUsX1V1F231IoO1zG0CYWXz3BuMVjj8IrVv/sPqfOdz8TqUbzlOBe5J70ytHBr/YeRITLaxt+sfV3fZjbGFhLk4DvU8uAU6Q8iFISIk9t9Et6u/mWmrkZciK/i3kg2DR07+DpWrMiq2sh3/SQwLp3Q+8VZggvJ60LsrRfx7zlIRrLyHPN/z/XdZKC8yTO8tmmflJwdaKRMg3ZrNPXEpsYO8E7uPVwhgPOYernZBOz+yo465o3OjXJJxwNTrlaDCM5RTbzMX76dyYXkn7A2DYU9OinrQsV3mQxXbZTMekbxhrcf7a1UcuM0oWRepst/MHQj+zi04+DocVAh0mr57EgztVpWMn7HpmhjVWpVn3p3jyzSnTbj8PJCgD+pMPEiaZ4n0KPB0YjAQKax3opZC59mkcqWLInbZUiaDI4fOXIoUep/Eoh9Q/eAXEo6fpLJOxh14lVEE8U91qTefxRALPq6cYwRQc82wH6NvEiMJZlsVvCkAizOj3XAfgXlZvi4SpxT5xAZed+oVLTbH02nPj+ojzbZSY4L6F3uXjsMAbfqz27RwIxrzDk+hXyr0ueypYTNp0lSwIVwcnyp5gb3/nj43AlVhC3u3MLDdCSf5dxenA1PizkDg5BKYazDc3eX0pd120PLeZHJSmtPTUW6X+TtkVxOY8er/PGvCZ3x13DNqCI/tyVLKmNdFbh7QHUpp1/1gGr7cgodCdmIs4piDBD1BwP/+8YqBdLX7aGD2+RQQNvnaJLwTQob+R6rPma3Qov1lAFd4TdBCSWX+Eyth2rEBjFHRzfdpp4aCRSSDv2GTrTUCR0e06AeH42QG7uANhVtdhc2uK7cwjKPg1ZCo8Xg6XD+3VUgxw4osbYo0k6aB/Uas58ldFuORLmlUrR9keeD6GyV4C1vhnsk5Sf/mHqCzWC+1OOBakWYD2DSDREOpOfNk/zDfb7llOKEV8LPl33mdyx9856Q9qjfMd8m X-OriginatorOrg: outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 7e07cf1e-8647-4a9c-0b79-08dbb94a8889 X-MS-Exchange-CrossTenant-AuthSource: AS8P250MB0744.EURP250.PROD.OUTLOOK.COM X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 19 Sep 2023 19:56:37.4787 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-Transport-CrossTenantHeadersStamped: DU2P250MB0303 Subject: [FFmpeg-devel] [PATCH 02/42] avcodec/refstruct: Add simple API for refcounted objects X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Cc: Andreas Rheinhardt Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" X-TUID: vqZk5udtvE0Y For now, this API is supposed to replace all the internal uses of reference counted objects in libavcodec; "internal" here means that the object is created in libavcodec and is never put directly in the hands of anyone outside of it. It is intended to be made public eventually, but for now I enjoy the ability to modify it freely. Several shortcomings of the AVBuffer API motivated this API: a) The unnecessary allocations (and ensuing error checks) when using the API. Besides the need for runtime checks it imposes upon the developer the burden of thinking through what happens in case an error happens. Furthermore, these error paths are typically not covered by FATE. b) The AVBuffer API is designed with buffers and not with objects in mind: The type for the actual buffers used is uint8_t*; it pretends to be able to make buffers writable, but this is wrong in case the buffer is not a POD. Another instance of this thinking is the lack of a reset callback in the AVBufferPool API. c) The AVBuffer API incurs unnecessary indirections by going through the AVBufferRef.data pointer. In case the user tries to avoid this indirection and stores a pointer to AVBuffer.data separately (which also allows to use the correct type), the user has to keep these two pointers in sync in case they can change (and in any case has two pointers occupying space in the containing context). See the following commit using this API for H.264 parameter sets for an example of the removal of such syncing code as well as the casts involved in the parts where only the AVBufferRef* pointer was stored. d) Given that the AVBuffer API allows custom allocators, creating refcounted objects with dedicated free functions often involves a lot of boilerplate like this: obj = av_mallocz(sizeof(*obj)); ref = av_buffer_create((uint8_t*)obj, sizeof(*obj), free_func, opaque, 0); if (!ref) { av_free(obj); return AVERROR(ENOMEM); } (There is also a corresponding av_free() at the end of free_func().) This is now just obj = ff_refstruct_alloc_ext(sizeof(*obj), 0, opaque, free_func); if (!obj) return AVERROR(ENOMEM); See the subsequent patch for the framepool (i.e. get_buffer.c) for an example. This API does things differently; it is designed to be lightweight* as well as geared to the common case where the allocator of the underlying object does not matter as long as it is big enough and suitably aligned. This allows to allocate the user data together with the API's bookkeeping data which avoids an allocation as well as the need for separate pointers to the user data and the API's bookkeeping data. This entails that the actual allocation of the object is performed by refstruct, not the user. This is responsible for avoiding the boilerplate code mentioned in d). As a downside, custom allocators are not supported, but it will become apparent in subsequent commits that there are enough usecases to make it worthwhile. Another advantage of this API is that one only needs to include the relevant header if one uses the API and not when one includes the header or some other component that uses it. This is because there is no refstruct type analog of AVBufferRef. This brings with it one further downside: It is not apparent from the pointer itself whether the underlying object is managed by the refstruct API or whether this pointer is a reference to it (or merely a pointer to it). Finally, this API supports const-qualified opaque pointees; this will allow to avoid casting const away by the CBS code. *: Basically the only exception to the you-only-pay-for-what-you-use rule is that it always uses atomics for the refcount. Signed-off-by: Andreas Rheinhardt --- I am the most unsure about whether to use FFRefStructOpaque at all or not just a void*; the only beneficiary of this is CBS where it saves casting one const away. I am also open to other naming suggestions like RefObject (RefObj?) for this API. libavcodec/Makefile | 1 + libavcodec/refstruct.c | 139 +++++++++++++++++++++++++++++++++++++++ libavcodec/refstruct.h | 145 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 285 insertions(+) create mode 100644 libavcodec/refstruct.c create mode 100644 libavcodec/refstruct.h diff --git a/libavcodec/Makefile b/libavcodec/Makefile index bf3b0a93f9..7541f38535 100644 --- a/libavcodec/Makefile +++ b/libavcodec/Makefile @@ -55,6 +55,7 @@ OBJS = ac3_parser.o \ profiles.o \ qsv_api.o \ raw.o \ + refstruct.o \ utils.o \ version.o \ vlc.o \ diff --git a/libavcodec/refstruct.c b/libavcodec/refstruct.c new file mode 100644 index 0000000000..917cf6b7ac --- /dev/null +++ b/libavcodec/refstruct.c @@ -0,0 +1,139 @@ +/* + * This file is part of FFmpeg. + * + * FFmpeg is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * FFmpeg is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#include +#include +#include + +#include "internal.h" +#include "refstruct.h" + +#include "libavutil/macros.h" +#include "libavutil/mem.h" + +typedef struct RefCount { + /** + * An uintptr_t is big enough to hold the address of every reference, + * so no overflow can happen when incrementing the refcount as long as + * the user does not throw away references. + */ + atomic_uintptr_t refcount; + FFRefStructOpaque opaque; + void (*free_cb)(FFRefStructOpaque opaque, void *obj); +} RefCount; + +#if __STDC_VERSION__ >= 201112L +#define REFCOUNT_OFFSET FFALIGN(sizeof(RefCount), FFMAX3(STRIDE_ALIGN, 16, _Alignof(max_align_t))) +#else +#define REFCOUNT_OFFSET FFALIGN(sizeof(RefCount), FFMAX(STRIDE_ALIGN, 16)) +#endif + +static RefCount *get_refcount(void *obj) +{ + return (RefCount*)((char*)obj - REFCOUNT_OFFSET); +} + +static void *get_userdata(void *buf) +{ + return (char*)buf + REFCOUNT_OFFSET; +} + +static void refcount_init(RefCount *ref, FFRefStructOpaque opaque, + void (*free_cb)(FFRefStructOpaque opaque, void *obj)) +{ + atomic_init(&ref->refcount, 1); + ref->opaque = opaque; + ref->free_cb = free_cb; +} + +void *ff_refstruct_alloc_ext_c(size_t size, unsigned flags, FFRefStructOpaque opaque, + void (*free_cb)(FFRefStructOpaque opaque, void *obj)) +{ + void *buf, *obj; + + if (size > SIZE_MAX - REFCOUNT_OFFSET) + return NULL; + buf = av_malloc(size + REFCOUNT_OFFSET); + if (!buf) + return NULL; + refcount_init(buf, opaque, free_cb); + obj = get_userdata(buf); + if (!(flags & FF_REFSTRUCT_FLAG_NO_ZEROING)) + memset(obj, 0, size); + + return obj; +} + +void *ff_refstruct_allocz(size_t size) +{ + return ff_refstruct_alloc_ext(size, 0, NULL, NULL); +} + +void ff_refstruct_unref(void *objp) +{ + void *obj; + RefCount *ref; + + memcpy(&obj, objp, sizeof(obj)); + if (!obj) + return; + memcpy(objp, &(void *){ NULL }, sizeof(obj)); + + ref = get_refcount(obj); + if (atomic_fetch_sub_explicit(&ref->refcount, 1, memory_order_acq_rel) == 1) { + if (ref->free_cb) + ref->free_cb(ref->opaque, obj); + av_free(ref); + } + + return; +} + +void *ff_refstruct_ref(void *obj) +{ + RefCount *ref = get_refcount(obj); + + atomic_fetch_add_explicit(&ref->refcount, 1, memory_order_relaxed); + + return obj; +} + +const void *ff_refstruct_ref_c(const void *obj) +{ + /* Casting const away here is fine, as it is only supposed + * to apply to the user's data and not our bookkeeping data. */ + RefCount *ref = get_refcount((void*)obj); + + atomic_fetch_add_explicit(&ref->refcount, 1, memory_order_relaxed); + + return obj; +} + +void ff_refstruct_replace(void *dstp, const void *src) +{ + const void *dst; + memcpy(&dst, dstp, sizeof(dst)); + + if (src == dst) + return; + ff_refstruct_unref(dstp); + if (src) { + dst = ff_refstruct_ref_c(src); + memcpy(dstp, &dst, sizeof(dst)); + } +} diff --git a/libavcodec/refstruct.h b/libavcodec/refstruct.h new file mode 100644 index 0000000000..0086717c17 --- /dev/null +++ b/libavcodec/refstruct.h @@ -0,0 +1,145 @@ +/* + * This file is part of FFmpeg. + * + * FFmpeg is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * FFmpeg is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with FFmpeg; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + */ + +#ifndef AVCODEC_REFSTRUCT_H +#define AVCODEC_REFSTRUCT_H + +#include + +/** + * RefStruct is an API for creating reference-counted objects + * with minimal overhead. The API is designed for objects, + * not buffers like the AVBuffer API. The main differences + * to the AVBuffer API are as follows: + * + * - It uses void* instead of uint8_t* as its base type due to + * its focus on objects. + * - There are no equivalents of AVBuffer and AVBufferRef. + * E.g. there is no way to get the usable size of the object: + * The user is supposed to know what is at the other end of + * the pointer. It also avoids one level of indirection. + * - Custom allocators are not supported. This allows to simplify + * the implementation and reduce the amount of allocations. + * - It also has the advantage that the user's free callback need + * only free the resources owned by the object, but not the + * object itself. + * - Because referencing (and replacing) an object managed by the + * RefStruct API does not involve allocations, they can not fail + * and therefore need not be checked. + * + * @note Referencing and unreferencing the buffers is thread-safe and thus + * may be done from multiple threads simultaneously without any need for + * additional locking. + */ + +/** + * This union is used for all opaque parameters in this API to spare the user + * to cast const away in case the opaque to use is const-qualified. + * + * The functions provided by this API with an FFRefStructOpaque come in pairs + * named foo_c and foo. The foo function accepts void* as opaque and is just + * a wrapper around the foo_c function; "_c" means "(potentially) const". + */ +typedef union { + void *nc; + const void *c; +} FFRefStructOpaque; + +/** + * If this flag is set in ff_refstruct_alloc_ext_c(), the object will not + * be initially zeroed. + */ +#define FF_REFSTRUCT_FLAG_NO_ZEROING (1 << 0) + +/** + * Allocate a refcounted object of usable size `size` managed via + * the RefStruct API. + * + * By default (in the absence of flags to the contrary), + * the returned object is initially zeroed. + * + * @param size Desired usable size of the returned object. + * @param flags A bitwise combination of FF_REFSTRUCT_FLAG_* flags. + * @param opaque A pointer that will be passed to the free_cb callback. + * @param free_cb A callback for freeing this object's content + * when its reference count reaches zero; + * it must not free the object itself. + * @return A pointer to an object of the desired size or NULL on failure. + */ +void *ff_refstruct_alloc_ext_c(size_t size, unsigned flags, FFRefStructOpaque opaque, + void (*free_cb)(FFRefStructOpaque opaque, void *obj)); + +/** + * A wrapper around ff_refstruct_alloc_ext_c() for the common case + * of a non-const qualified opaque. + * + * @see ff_refstruct_alloc_ext_c() + */ +static inline +void *ff_refstruct_alloc_ext(size_t size, unsigned flags, void *opaque, + void (*free_cb)(FFRefStructOpaque opaque, void *obj)) +{ + return ff_refstruct_alloc_ext_c(size, flags, (FFRefStructOpaque){.nc = opaque}, + free_cb); +} + +/** + * Equivalent to ff_refstruct_alloc_ext(size, 0, NULL, NULL) + */ +void *ff_refstruct_allocz(size_t size); + +/** + * Decrement the reference count of the underlying object and automatically + * free the object if there are no more references to it. + * + * `*objp == NULL` is legal and a no-op. + * + * @param objp Pointer to a pointer that is either NULL or points to an object + * managed via this API. `*objp` is set to NULL on return. + */ +void ff_refstruct_unref(void *objp); + +/** + * Create a new reference to an object managed via this API, + * i.e. increment the reference count of the underlying object + * and return obj. + * @return a pointer equal to obj. + */ +void *ff_refstruct_ref(void *obj); + +/** + * Analog of ff_refstruct_ref(), but for constant objects. + * @see ff_refstruct_ref() + */ +const void *ff_refstruct_ref_c(const void *obj); + +/** + * Ensure `*dstp` refers to the same object as src. + * + * If `*dstp` is already equal to src, do nothing. Otherwise unreference `*dstp` + * and replace it with a new reference to src in case `src != NULL` (this + * involves incrementing the reference count of src's underlying object) or + * with NULL otherwise. + * + * @param dstp Pointer to a pointer that is either NULL or points to an object + * managed via this API. + * @param src A pointer to an object managed via this API or NULL. + */ +void ff_refstruct_replace(void *dstp, const void *src); + +#endif /* AVCODEC_REFSTRUCT_H */