1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module gstreamer.Promise; 26 27 private import glib.ConstructionException; 28 private import gobject.ObjectG; 29 private import gstreamer.Structure; 30 private import gstreamer.c.functions; 31 public import gstreamer.c.types; 32 33 34 /** 35 * The #GstPromise object implements the container for values that may 36 * be available later. i.e. a Future or a Promise in 37 * <https://en.wikipedia.org/wiki/Futures_and_promises>. 38 * As with all Future/Promise-like functionality, there is the concept of the 39 * producer of the value and the consumer of the value. 40 * 41 * A #GstPromise is created with gst_promise_new() by the consumer and passed 42 * to the producer to avoid thread safety issues with the change callback. 43 * A #GstPromise can be replied to with a value (or an error) by the producer 44 * with gst_promise_reply(). The exact value returned is defined by the API 45 * contract of the producer and %NULL may be a valid reply. 46 * gst_promise_interrupt() is for the consumer to 47 * indicate to the producer that the value is not needed anymore and producing 48 * that value can stop. The @GST_PROMISE_RESULT_EXPIRED state set by a call 49 * to gst_promise_expire() indicates to the consumer that a value will never 50 * be produced and is intended to be called by a third party that implements 51 * some notion of message handling such as #GstBus. 52 * A callback can also be installed at #GstPromise creation for 53 * result changes with gst_promise_new_with_change_func(). 54 * The change callback can be used to chain #GstPromises's together as in the 55 * following example. 56 * |[<!-- language="C" --> 57 * const GstStructure *reply; 58 * GstPromise *p; 59 * if (gst_promise_wait (promise) != GST_PROMISE_RESULT_REPLIED) 60 * return; // interrupted or expired value 61 * reply = gst_promise_get_reply (promise); 62 * if (error in reply) 63 * return; // propagate error 64 * p = gst_promise_new_with_change_func (another_promise_change_func, user_data, notify); 65 * pass p to promise-using API 66 * ]| 67 * 68 * Each #GstPromise starts out with a #GstPromiseResult of 69 * %GST_PROMISE_RESULT_PENDING and only ever transitions once 70 * into one of the other #GstPromiseResult's. 71 * 72 * In order to support multi-threaded code, gst_promise_reply(), 73 * gst_promise_interrupt() and gst_promise_expire() may all be from 74 * different threads with some restrictions and the final result of the promise 75 * is whichever call is made first. There are two restrictions on ordering: 76 * 77 * 1. That gst_promise_reply() and gst_promise_interrupt() cannot be called 78 * after gst_promise_expire() 79 * 2. That gst_promise_reply() and gst_promise_interrupt() 80 * cannot be called twice. 81 * 82 * The change function set with gst_promise_new_with_change_func() is 83 * called directly from either the gst_promise_reply(), 84 * gst_promise_interrupt() or gst_promise_expire() and can be called 85 * from an arbitrary thread. #GstPromise using APIs can restrict this to 86 * a single thread or a subset of threads but that is entirely up to the API 87 * that uses #GstPromise. 88 * 89 * Since: 1.14 90 */ 91 public class Promise 92 { 93 /** the main Gtk struct */ 94 protected GstPromise* gstPromise; 95 protected bool ownedRef; 96 97 /** Get the main Gtk struct */ 98 public GstPromise* getPromiseStruct(bool transferOwnership = false) 99 { 100 if (transferOwnership) 101 ownedRef = false; 102 return gstPromise; 103 } 104 105 /** the main Gtk struct as a void* */ 106 protected void* getStruct() 107 { 108 return cast(void*)gstPromise; 109 } 110 111 /** 112 * Sets our main struct and passes it to the parent class. 113 */ 114 public this (GstPromise* gstPromise, bool ownedRef = false) 115 { 116 this.gstPromise = gstPromise; 117 this.ownedRef = ownedRef; 118 } 119 120 121 /** */ 122 public static GType getType() 123 { 124 return gst_promise_get_type(); 125 } 126 127 /** 128 * Returns: a new #GstPromise 129 * 130 * Since: 1.14 131 * 132 * Throws: ConstructionException GTK+ fails to create the object. 133 */ 134 public this() 135 { 136 auto __p = gst_promise_new(); 137 138 if(__p is null) 139 { 140 throw new ConstructionException("null returned by new"); 141 } 142 143 this(cast(GstPromise*) __p); 144 } 145 146 /** 147 * @func will be called exactly once when transitioning out of 148 * %GST_PROMISE_RESULT_PENDING into any of the other #GstPromiseResult 149 * states. 150 * 151 * Params: 152 * func = a #GstPromiseChangeFunc to call 153 * userData = argument to call @func with 154 * notify = notification function that @user_data is no longer needed 155 * 156 * Returns: a new #GstPromise 157 * 158 * Since: 1.14 159 * 160 * Throws: ConstructionException GTK+ fails to create the object. 161 */ 162 public this(GstPromiseChangeFunc func, void* userData, GDestroyNotify notify) 163 { 164 auto __p = gst_promise_new_with_change_func(func, userData, notify); 165 166 if(__p is null) 167 { 168 throw new ConstructionException("null returned by new_with_change_func"); 169 } 170 171 this(cast(GstPromise*) __p); 172 } 173 174 /** 175 * Expire a @promise. This will wake up any waiters with 176 * %GST_PROMISE_RESULT_EXPIRED. Called by a message loop when the parent 177 * message is handled and/or destroyed (possibly unanswered). 178 * 179 * Since: 1.14 180 */ 181 public void expire() 182 { 183 gst_promise_expire(gstPromise); 184 } 185 186 /** 187 * Retrieve the reply set on @promise. @promise must be in 188 * %GST_PROMISE_RESULT_REPLIED and the returned structure is owned by @promise 189 * 190 * Returns: The reply set on @promise 191 * 192 * Since: 1.14 193 */ 194 public Structure getReply() 195 { 196 auto __p = gst_promise_get_reply(gstPromise); 197 198 if(__p is null) 199 { 200 return null; 201 } 202 203 return ObjectG.getDObject!(Structure)(cast(GstStructure*) __p); 204 } 205 206 /** 207 * Interrupt waiting for a @promise. This will wake up any waiters with 208 * %GST_PROMISE_RESULT_INTERRUPTED. Called when the consumer does not want 209 * the value produced anymore. 210 * 211 * Since: 1.14 212 */ 213 public void interrupt() 214 { 215 gst_promise_interrupt(gstPromise); 216 } 217 218 /** 219 * Set a reply on @promise. This will wake up any waiters with 220 * %GST_PROMISE_RESULT_REPLIED. Called by the producer of the value to 221 * indicate success (or failure). 222 * 223 * If @promise has already been interrupted by the consumer, then this reply 224 * is not visible to the consumer. 225 * 226 * Params: 227 * s = a #GstStructure with the the reply contents 228 * 229 * Since: 1.14 230 */ 231 public void reply(Structure s) 232 { 233 gst_promise_reply(gstPromise, (s is null) ? null : s.getStructureStruct(true)); 234 } 235 236 /** 237 * Wait for @promise to move out of the %GST_PROMISE_RESULT_PENDING state. 238 * If @promise is not in %GST_PROMISE_RESULT_PENDING then it will return 239 * immediately with the current result. 240 * 241 * Returns: the result of the promise 242 * 243 * Since: 1.14 244 */ 245 public GstPromiseResult wait() 246 { 247 return gst_promise_wait(gstPromise); 248 } 249 }