Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 471 insertions, 0 deletions

diff --git a/third_party/pipewire/spa/utils/hook.h b/third_party/pipewire/spa/utils/hook.h
new file mode 100644
index 0000000000..9b1a50b63b
--- /dev/null
+++ b/third_party/pipewire/spa/utils/hook.h
@@ -0,0 +1,471 @@
+/* Simple Plugin API
+ *
+ * Copyright © 2018 Wim Taymans
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"),
+ * to deal in the Software without restriction, including without limitation
+ * the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice (including the next
+ * paragraph) shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+ * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+#ifndef SPA_HOOK_H
+#define SPA_HOOK_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <spa/utils/defs.h>
+#include <spa/utils/list.h>
+
+/** \defgroup spa_interfaces Interfaces
+ *
+ * \brief Generic implementation of implementation-independent interfaces
+ *
+ * A SPA Interface is a generic struct that, together with a few macros,
+ * provides a generic way of invoking methods on objects without knowing the
+ * details of the implementation.
+ *
+ * The primary interaction with interfaces is through macros that expand into
+ * the right method call. For the implementation of an interface, we need two
+ * structs and a macro to invoke the `bar` method:
+ *
+ * \code{.c}
+ * // this struct must be public and defines the interface to a
+ * // struct foo
+ * struct foo_methods {
+ *     uint32_t version;
+ *     void (*bar)(void *object, const char *msg);
+ * };
+ *
+ * // this struct does not need to be public
+ * struct foo {
+ *     struct spa_interface iface; // must be first element, see foo_bar()
+ *     int some_other_field;
+ *     ...
+ * };
+ *
+ * // if struct foo is private, we need to cast to a
+ * // generic spa_interface object
+ * #define foo_bar(obj, ...) ({ \
+ *     struct foo *f = obj;
+ *     spa_interface_call((struct spa_interface *)f, // pointer to spa_interface in foo
+ *                        struct foo_methods, // type of callbacks
+ *                        bar, // name of methods
+ *                        0, // hardcoded version to match foo_methods->version
+ *                        __VA_ARGS__ // pass rest of args through
+ *                        );/
+ * })
+ * \endcode
+ *
+ * The `struct foo_methods` and the invocation macro `foo_bar()` must be
+ * available to the caller. The implementation of `struct foo` can be private.
+ *
+ * \code{.c}
+ * void main(void) {
+ *      struct foo *myfoo = get_foo_from_somewhere();
+ *      foo_bar(myfoo, "Invoking bar() on myfoo");
+ * }
+ * \endcode
+ * The expansion of `foo_bar()` resolves roughly into this code:
+ * \code{.c}
+ * void main(void) {
+ *     struct foo *myfoo = get_foo_from_somewhere();
+ *     // foo_bar(myfoo, "Invoking bar() on myfoo");
+ *     const struct foo_methods *methods = ((struct spa_interface*)myfoo)->cb;
+ *     if (0 >= methods->version && // version check
+ *         methods->bar) // compile error if this function does not exist,
+ *             methods->bar(myfoo, "Invoking bar() on myfoo");
+ * }
+ * \endcode
+ *
+ * The typecast used in `foo_bar()` allows `struct foo` to be opaque to the
+ * caller. The implementation may assign the callback methods at object
+ * instantiation, and the caller will transparently invoke the method on the
+ * given object. For example, the following code assigns a different `bar()` method on
+ * Mondays - the caller does not need to know this.
+ * \code{.c}
+ *
+ * static void bar_stdout(struct foo *f, const char *msg) {
+ *     printf(msg);
+ * }
+ * static void bar_stderr(struct foo *f, const char *msg) {
+ *     fprintf(stderr, msg);
+ * }
+ *
+ * struct foo* get_foo_from_somewhere() {
+ *     struct foo *f = calloc(sizeof struct foo);
+ *     // illustrative only, use SPA_INTERFACE_INIT()
+ *     f->iface->cb = (struct foo_methods*) { .bar = bar_stdout };
+ *     if (today_is_monday)
+ *         f->iface->cb = (struct foo_methods*) { .bar = bar_stderr };
+ *     return f;
+ * }
+ * \endcode
+ */
+
+/**
+ * \addtogroup spa_interfaces
+ * \{
+ */
+
+/** \struct spa_callbacks
+ * Callbacks, contains the structure with functions and the data passed
+ * to the functions.  The structure should also contain a version field that
+ * is checked. */
+struct spa_callbacks {
+	const void *funcs;
+	void *data;
+};
+
+/** Check if a callback \a c is of at least version \a v */
+#define SPA_CALLBACK_VERSION_MIN(c,v) ((c) && ((v) == 0 || (c)->version > (v)-1))
+
+/** Check if a callback \a c has method \a m of version \a v */
+#define SPA_CALLBACK_CHECK(c,m,v) (SPA_CALLBACK_VERSION_MIN(c,v) && (c)->m)
+
+/**
+ * Initialize the set of functions \a funcs as a \ref spa_callbacks, together
+ * with \a _data.
+ */
+#define SPA_CALLBACKS_INIT(_funcs,_data) (struct spa_callbacks){ _funcs, _data, }
+
+/** \struct spa_interface
+ */
+struct spa_interface {
+	const char *type;
+	uint32_t version;
+	struct spa_callbacks cb;
+};
+
+/**
+ * Initialize a \ref spa_interface.
+ *
+ * \code{.c}
+ * const static struct foo_methods foo_funcs = {
+ *    .bar = some_bar_implementation,
+ * };
+ *
+ * struct foo *f = malloc(...);
+ * f->iface = SPA_INTERFACE_INIT("foo type", 0, foo_funcs, NULL);
+ * \endcode
+ *
+ */
+#define SPA_INTERFACE_INIT(_type,_version,_funcs,_data) \
+	(struct spa_interface){ _type, _version, SPA_CALLBACKS_INIT(_funcs,_data), }
+
+/**
+ * Invoke method named \a method in the \a callbacks.
+ * The \a method_type defines the type of the method struct.
+ * Returns true if the method could be called, false otherwise.
+ */
+#define spa_callbacks_call(callbacks,type,method,vers,...)			\
+({										\
+	const type *_f = (const type *) (callbacks)->funcs;			\
+	bool _res = SPA_CALLBACK_CHECK(_f,method,vers);				\
+	if (SPA_LIKELY(_res))							\
+		_f->method((callbacks)->data, ## __VA_ARGS__);			\
+	_res;									\
+})
+
+/**
+ * True if the \a callbacks are of version \a vers, false otherwise
+ */
+#define spa_callback_version_min(callbacks,type,vers)				\
+({										\
+	const type *_f = (const type *) (callbacks)->funcs;			\
+	SPA_CALLBACK_VERSION_MIN(_f,vers);					\
+})
+
+/**
+ * True if the \a callbacks contains \a method of version
+ * \a vers, false otherwise
+ */
+#define spa_callback_check(callbacks,type,method,vers)				\
+({										\
+	const type *_f = (const type *) (callbacks)->funcs;			\
+	SPA_CALLBACK_CHECK(_f,method,vers);					\
+})
+
+/**
+ * Invoke method named \a method in the \a callbacks.
+ * The \a method_type defines the type of the method struct.
+ *
+ * The return value is stored in \a res.
+ */
+#define spa_callbacks_call_res(callbacks,type,res,method,vers,...)		\
+({										\
+	const type *_f = (const type *) (callbacks)->funcs;			\
+	if (SPA_LIKELY(SPA_CALLBACK_CHECK(_f,method,vers)))			\
+		res = _f->method((callbacks)->data, ## __VA_ARGS__);		\
+	res;									\
+})
+
+/**
+ * True if the \a iface's callbacks are of version \a vers, false otherwise
+ */
+#define spa_interface_callback_version_min(iface,method_type,vers)		\
+   spa_callback_version_min(&(iface)->cb, method_type, vers)
+
+/**
+ * True if the \a iface's callback \a method is of version \a vers
+ * and exists, false otherwise
+ */
+#define spa_interface_callback_check(iface,method_type,method,vers)		\
+   spa_callback_check(&(iface)->cb, method_type, method, vers)
+
+/**
+ * Invoke method named \a method in the callbacks on the given interface object.
+ * The \a method_type defines the type of the method struct, not the interface
+ * itself.
+ */
+#define spa_interface_call(iface,method_type,method,vers,...)			\
+	spa_callbacks_call(&(iface)->cb,method_type,method,vers,##__VA_ARGS__)
+
+/**
+ * Invoke method named \a method in the callbacks on the given interface object.
+ * The \a method_type defines the type of the method struct, not the interface
+ * itself.
+ *
+ * The return value is stored in \a res.
+ */
+#define spa_interface_call_res(iface,method_type,res,method,vers,...)			\
+	spa_callbacks_call_res(&(iface)->cb,method_type,res,method,vers,##__VA_ARGS__)
+
+/**
+ * \}
+ */
+
+/** \defgroup spa_hooks Hooks
+ *
+ * A SPA Hook is a data structure to keep track of callbacks. It is similar to
+ * the \ref spa_interfaces and typically used where an implementation allows
+ * for multiple external callback functions. For example, an implementation may
+ * use a hook list to implement signals with each caller using a hook to
+ * register callbacks to be invoked on those signals.
+ *
+ * The below (pseudo)code is a minimal example outlining the use of hooks:
+ * \code{.c}
+ * // the public interface
+ * #define VERSION_BAR_EVENTS 0 // version of the vtable
+ * struct bar_events {
+ *    uint32_t version; // NOTE: an integral member named `version`
+ *                      //       must be present in the vtable
+ *    void (*boom)(void *data, const char *msg);
+ * };
+ *
+ * // private implementation
+ * struct party {
+ *     struct spa_hook_list bar_list;
+ * };
+ *
+ * void party_add_event_listener(struct party *p, struct spa_hook *listener,
+ *                               const struct bar_events *events, void *data)
+ * {
+ *    spa_hook_list_append(&p->bar_list, listener, events, data);
+ * }
+ *
+ * static void party_on(struct party *p)
+ * {
+ *     // NOTE: this is a macro, it evaluates to an integer,
+ *     //       which is the number of hooks called
+ *     spa_hook_list_call(&p->list,
+ *                        struct bar_events, // vtable type
+ *                        boom,              // function name
+ *                        0,                 // hardcoded version,
+ *                                           //     usually the version in which `boom`
+ *                                           //     has been added to the vtable
+ *                        "party on, wayne"  // function argument(s)
+ *                        );
+ * }
+ * \endcode
+ *
+ * In the caller, the hooks can be used like this:
+ * \code{.c}
+ * static void boom_cb(void *data, const char *msg) {
+ *      // data is userdata from main()
+ *      printf("%s", msg);
+ * }
+ *
+ * static const struct bar_events events = {
+ *    .version = VERSION_BAR_EVENTS, // version of the implemented interface
+ *    .boom = boom_cb,
+ * };
+ *
+ * void main(void) {
+ *      void *userdata = whatever;
+ *      struct spa_hook hook;
+ *      struct party *p = start_the_party();
+ *
+ *      party_add_event_listener(p, &hook, &events, userdata);
+ *
+ *      mainloop();
+ *      return 0;
+ * }
+ *
+ * \endcode
+ */
+
+/**
+ * \addtogroup spa_hooks
+ * \{
+ */
+
+/** \struct spa_hook_list
+ * A list of hooks. This struct is primarily used by
+ * implementation that use multiple caller-provided \ref spa_hook. */
+struct spa_hook_list {
+	struct spa_list list;
+};
+
+
+/** \struct spa_hook
+ * A hook, contains the structure with functions and the data passed
+ * to the functions.
+ *
+ * A hook should be treated as opaque by the caller.
+ */
+struct spa_hook {
+	struct spa_list link;
+	struct spa_callbacks cb;
+	/** callback and data for the hook list, private to the
+	  * hook_list implementor */
+	void (*removed) (struct spa_hook *hook);
+	void *priv;
+};
+
+/** Initialize a hook list to the empty list*/
+static inline void spa_hook_list_init(struct spa_hook_list *list)
+{
+	spa_list_init(&list->list);
+}
+
+static inline bool spa_hook_list_is_empty(struct spa_hook_list *list)
+{
+	return spa_list_is_empty(&list->list);
+}
+
+/** Append a hook. */
+static inline void spa_hook_list_append(struct spa_hook_list *list,
+					struct spa_hook *hook,
+					const void *funcs, void *data)
+{
+	spa_zero(*hook);
+	hook->cb = SPA_CALLBACKS_INIT(funcs, data);
+	spa_list_append(&list->list, &hook->link);
+}
+
+/** Prepend a hook */
+static inline void spa_hook_list_prepend(struct spa_hook_list *list,
+					 struct spa_hook *hook,
+					 const void *funcs, void *data)
+{
+	spa_zero(*hook);
+	hook->cb = SPA_CALLBACKS_INIT(funcs, data);
+	spa_list_prepend(&list->list, &hook->link);
+}
+
+/** Remove a hook */
+static inline void spa_hook_remove(struct spa_hook *hook)
+{
+	spa_list_remove(&hook->link);
+	if (hook->removed)
+		hook->removed(hook);
+}
+
+/** Remove all hooks from the list */
+static inline void spa_hook_list_clean(struct spa_hook_list *list)
+{
+	struct spa_hook *h;
+	spa_list_consume(h, &list->list, link)
+		spa_hook_remove(h);
+}
+
+static inline void
+spa_hook_list_isolate(struct spa_hook_list *list,
+		struct spa_hook_list *save,
+		struct spa_hook *hook,
+		const void *funcs, void *data)
+{
+	/* init save list and move hooks to it */
+	spa_hook_list_init(save);
+	spa_list_insert_list(&save->list, &list->list);
+	/* init hooks and add single hook */
+	spa_hook_list_init(list);
+	spa_hook_list_append(list, hook, funcs, data);
+}
+
+static inline void
+spa_hook_list_join(struct spa_hook_list *list,
+		struct spa_hook_list *save)
+{
+	spa_list_insert_list(&list->list, &save->list);
+}
+
+#define spa_hook_list_call_simple(l,type,method,vers,...)			\
+({										\
+	struct spa_hook_list *_l = l;						\
+	struct spa_hook *_h, *_t;						\
+	spa_list_for_each_safe(_h, _t, &_l->list, link)				\
+		spa_callbacks_call(&_h->cb,type,method,vers, ## __VA_ARGS__);	\
+})
+
+/** Call all hooks in a list, starting from the given one and optionally stopping
+ * after calling the first non-NULL function, returns the number of methods
+ * called */
+#define spa_hook_list_do_call(l,start,type,method,vers,once,...)		\
+({										\
+	struct spa_hook_list *_list = l;					\
+	struct spa_list *_s = start ? (struct spa_list *)start : &_list->list;	\
+	struct spa_hook _cursor = { 0 }, *_ci;					\
+	int _count = 0;								\
+	spa_list_cursor_start(_cursor, _s, link);				\
+	spa_list_for_each_cursor(_ci, _cursor, &_list->list, link) {		\
+		if (spa_callbacks_call(&_ci->cb,type,method,vers, ## __VA_ARGS__)) {		\
+			_count++;						\
+			if (once)						\
+				break;						\
+		}								\
+	}									\
+	spa_list_cursor_end(_cursor, link);					\
+	_count;									\
+})
+
+/**
+ * Call the method named \a m for each element in list \a l.
+ * \a t specifies the type of the callback struct.
+ */
+#define spa_hook_list_call(l,t,m,v,...)			spa_hook_list_do_call(l,NULL,t,m,v,false,##__VA_ARGS__)
+/**
+ * Call the method named \a m for each element in list \a l, stopping after
+ * the first invocation.
+ * \a t specifies the type of the callback struct.
+ */
+#define spa_hook_list_call_once(l,t,m,v,...)		spa_hook_list_do_call(l,NULL,t,m,v,true,##__VA_ARGS__)
+
+#define spa_hook_list_call_start(l,s,t,m,v,...)		spa_hook_list_do_call(l,s,t,m,v,false,##__VA_ARGS__)
+#define spa_hook_list_call_once_start(l,s,t,m,v,...)	spa_hook_list_do_call(l,s,t,m,v,true,##__VA_ARGS__)
+
+/**
+ * \}
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* SPA_HOOK_H */