From 19832bd3b36e8990a3e2e811451d16b3cf04fd38 Mon Sep 17 00:00:00 2001 From: Xavier Claessens Date: Mon, 18 Sep 2023 14:38:25 -0400 Subject: [PATCH] GstShmAllocator: Add documentation Sponsored-by: Netflix Inc. Part-of: --- .../gst-libs/gst/allocators/gstshmallocator.c | 38 +++++++++++++++++++ .../gst-libs/gst/allocators/gstshmallocator.h | 31 +++++++++++++++ 2 files changed, 69 insertions(+) diff --git a/subprojects/gst-plugins-base/gst-libs/gst/allocators/gstshmallocator.c b/subprojects/gst-plugins-base/gst-libs/gst/allocators/gstshmallocator.c index db92b09e3f..03ff40cba2 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/allocators/gstshmallocator.c +++ b/subprojects/gst-plugins-base/gst-libs/gst/allocators/gstshmallocator.c @@ -21,6 +21,25 @@ * Boston, MA 02110-1301, USA. */ +/** + * SECTION:gstshmallocator + * @title: GstShmAllocator + * @short_description: Allocator for file-descriptor backed shared memory + * @see_also: #GstMemory and #GstFdAllocator + * + * This is a subclass of #GstFdAllocator that implements the + * gst_allocator_alloc() method using `memfd_create()` when available, POSIX + * `shm_open()` otherwise. Platforms not supporting any of those (Windows) will + * always return %NULL. + * + * Note that allocating new shared memories has a significant performance cost, + * it is thus recommended to keep a pool of pre-allocated #GstMemory, using + * #GstBufferPool. For that reason, this allocator has the + * %GST_ALLOCATOR_FLAG_NO_COPY flag set. + * + * Since: 1.24 + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif @@ -161,6 +180,14 @@ gst_shm_allocator_init (GstShmAllocator * self) GST_OBJECT_FLAG_SET (self, GST_ALLOCATOR_FLAG_NO_COPY); } +/** + * gst_shm_allocator_init_once: + * + * Register a #GstShmAllocator using gst_allocator_register() with the name + * %GST_ALLOCATOR_SHM. This is no-op after the first call. + * + * Since: 1.24 + */ void gst_shm_allocator_init_once (void) { @@ -177,6 +204,17 @@ gst_shm_allocator_init_once (void) } } +/** + * gst_shm_allocator_get: + * + * Get the #GstShmAllocator singleton previously registered with + * gst_shm_allocator_init_once(). + * + * Returns: (transfer full) (nullable): a #GstAllocator or %NULL if + * gst_shm_allocator_init_once() has not been previously called. + * + * Since: 1.24 + */ GstAllocator * gst_shm_allocator_get (void) { diff --git a/subprojects/gst-plugins-base/gst-libs/gst/allocators/gstshmallocator.h b/subprojects/gst-plugins-base/gst-libs/gst/allocators/gstshmallocator.h index 97ab832934..90889f543b 100644 --- a/subprojects/gst-plugins-base/gst-libs/gst/allocators/gstshmallocator.h +++ b/subprojects/gst-plugins-base/gst-libs/gst/allocators/gstshmallocator.h @@ -27,8 +27,39 @@ G_BEGIN_DECLS +/** + * GST_ALLOCATOR_SHM: + * + * Name of this allocator, to be used for example with gst_allocator_find() and + * gst_memory_is_type(). + * + * Since: 1.24 + */ #define GST_ALLOCATOR_SHM "shm" +/** + * GstShmAllocator: + * + * Private intance object for #GstShmAllocator. + * + * Since: 1.24 + */ + +/** + * GstShmAllocatorClass.parent_class: + * + * Parent Class. + * + * Since: 1.24 + */ + +/** + * GST_TYPE_SHM_ALLOCATOR: + * + * Macro that returns the #GstShmAllocator type. + * + * Since: 1.24 + */ #define GST_TYPE_SHM_ALLOCATOR gst_shm_allocator_get_type () GST_ALLOCATORS_API G_DECLARE_FINAL_TYPE (GstShmAllocator, gst_shm_allocator, GST, SHM_ALLOCATOR, GstFdAllocator)