gst/gstpromise.h

   1 /* GStreamer
   2  * Copyright (C) 2017 Matthew Waters <matthew@centricular.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef __GST_PROMISE_H__
  21 #define __GST_PROMISE_H__
  22
  23 #include <gst/gst.h>
  24
  25 G_BEGIN_DECLS
  26
  27 GST_API
  28 GType gst_promise_get_type(void);
  29 #define GST_TYPE_PROMISE            (gst_promise_get_type())
  30 #define GST_PROMISE(obj)            ((GstPromise *) obj)
  31
  32 typedef struct _GstPromise GstPromise;
  33
  34 /**
  35  * GstPromiseResult:
  36  * @GST_PROMISE_RESULT_PENDING: Initial state. Waiting for transition to any
  37  *      other state.
  38  * @GST_PROMISE_RESULT_INTERRUPTED: Interrupted by the consumer as it doesn't
  39  *      want the value anymore.
  40  * @GST_PROMISE_RESULT_REPLIED: A producer marked a reply
  41  * @GST_PROMISE_RESULT_EXPIRED: The promise expired (the carrying object
  42  *      lost all refs) and the promise will never be fulfilled.
  43  *
  44  * The result of a #GstPromise
  45  *
  46  * Since: 1.14
  47  */
  48 typedef enum
  49 {
  50   GST_PROMISE_RESULT_PENDING,
  51   GST_PROMISE_RESULT_INTERRUPTED,
  52   GST_PROMISE_RESULT_REPLIED,
  53   GST_PROMISE_RESULT_EXPIRED,
  54 } GstPromiseResult;
  55
  56 /**
  57  * GstPromiseChangeFunc:
  58  * @promise: a #GstPromise
  59  * @user_data: (closure): user data
  60  *
  61  * Since: 1.14
  62  */
  63 typedef void (*GstPromiseChangeFunc) (GstPromise * promise, gpointer user_data);
  64
  65 /**
  66  * GstPromise:
  67  * @parent: parent #GstMiniObject
  68  *
  69  * Since: 1.14
  70  */
  71 struct _GstPromise
  72 {
  73   GstMiniObject         parent;
  74 };
  75
  76 GST_API
  77 GstPromise *            gst_promise_new                     (void);
  78 GST_API
  79 GstPromise *            gst_promise_new_with_change_func    (GstPromiseChangeFunc func,
  80                                                              gpointer user_data,
  81                                                              GDestroyNotify notify);
  82
  83 GST_API
  84 GstPromiseResult        gst_promise_wait                    (GstPromise * promise);
  85 GST_API
  86 void                    gst_promise_reply                   (GstPromise * promise,
  87                                                              GstStructure * s);
  88 GST_API
  89 void                    gst_promise_interrupt               (GstPromise * promise);
  90 GST_API
  91 void                    gst_promise_expire                  (GstPromise * promise);
  92
  93 GST_API
  94 const GstStructure *    gst_promise_get_reply               (GstPromise * promise);
  95
  96 /**
  97  * gst_promise_ref:
  98  * @promise: a #GstPromise.
  99  *
 100  * Increases the refcount of the given @promise by one.
 101  *
 102  * Returns: (transfer full): @promise
 103  *
 104  * Since: 1.14
 105  */
 106 static inline GstPromise *
 107 gst_promise_ref (GstPromise * promise)
 108 {
 109   return (GstPromise *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (promise));
 110 }
 111
 112 /**
 113  * gst_promise_unref:
 114  * @promise: (transfer full): a #GstPromise.
 115  *
 116  * Decreases the refcount of the promise. If the refcount reaches 0, the
 117  * promise will be freed.
 118  *
 119  * Since: 1.14
 120  */
 121 static inline void
 122 gst_promise_unref (GstPromise * promise)
 123 {
 124   gst_mini_object_unref (GST_MINI_OBJECT_CAST (promise));
 125 }
 126
 127 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 128 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstPromise, gst_promise_unref)
 129 #endif
 130
 131 G_END_DECLS
 132
 133 #endif /* __GST_PROMISE_H__ */