summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLauro Moura <lauromoura@expertisesolutions.com.br>2019-10-15 10:10:53 -0300
committerLauro Moura <lauromoura@expertisesolutions.com.br>2019-10-15 10:10:53 -0300
commit64e22aaadad980d65e2bb2531374b399f0c876f8 (patch)
treecaad107c94e01202b7f437876832e934f800cef9
parentc4c372c47d6a7a324e129cfd94cf1541d5842cf5 (diff)
csharp: Fix promises docs and hide api
Summary: ref T8293 Reviewers: felipealmeida, brunobelo, segfaultxavi, woohyun Reviewed By: brunobelo Subscribers: cedric, #reviewers, #committers Tags: #efl Maniphest Tasks: T8293 Differential Revision: https://phab.enlightenment.org/D10331
-rw-r--r--src/bindings/mono/eina_mono/eina_promises.cs69
1 files changed, 49 insertions, 20 deletions
diff --git a/src/bindings/mono/eina_mono/eina_promises.cs b/src/bindings/mono/eina_mono/eina_promises.cs
index 897d200..a2cef0d 100644
--- a/src/bindings/mono/eina_mono/eina_promises.cs
+++ b/src/bindings/mono/eina_mono/eina_promises.cs
@@ -2,6 +2,7 @@ using System;
2using System.Runtime.InteropServices; 2using System.Runtime.InteropServices;
3using System.Collections.Generic; 3using System.Collections.Generic;
4using System.Linq; 4using System.Linq;
5using System.ComponentModel;
5 6
6 7
7using static Eina.EinaNative.PromiseNativeMethods; 8using static Eina.EinaNative.PromiseNativeMethods;
@@ -12,6 +13,7 @@ namespace Eina
12namespace EinaNative 13namespace EinaNative
13{ 14{
14 15
16[EditorBrowsable(EditorBrowsableState.Never)]
15static internal class PromiseNativeMethods 17static internal class PromiseNativeMethods
16{ 18{
17 internal delegate void Promise_Cancel_Cb(IntPtr data, IntPtr dead); 19 internal delegate void Promise_Cancel_Cb(IntPtr data, IntPtr dead);
@@ -71,14 +73,16 @@ static internal class PromiseNativeMethods
71/// 73///
72/// With a Promise you can attach futures to it, which will be used to notify of the value being available. 74/// With a Promise you can attach futures to it, which will be used to notify of the value being available.
73/// 75///
74/// Since Efl 1.23. 76/// <para>Since Efl 1.23.</para>
75/// </summary> 77/// </summary>
76public class Promise : IDisposable 78public class Promise : IDisposable
77{ 79{
78 internal IntPtr Handle; 80 internal IntPtr Handle;
79 private GCHandle CleanupHandle; 81 private GCHandle CleanupHandle;
80 82
81 /// <summary>Delegate for functions that will be called upon a promise cancellation.</summary> 83 /// <summary>Delegate for functions that will be called upon a promise cancellation.
84 /// <para>Since EFL 1.23.</para>
85 /// </summary>
82 public delegate void CancelCb(); 86 public delegate void CancelCb();
83 87
84 /// <summary> 88 /// <summary>
@@ -86,6 +90,7 @@ public class Promise : IDisposable
86 /// 90 ///
87 /// Currently, creating a promise directly uses the Main Loop scheduler the source of notifications (i.e. the 91 /// Currently, creating a promise directly uses the Main Loop scheduler the source of notifications (i.e. the
88 /// future callbacks will be called mainly from a loop iteration). 92 /// future callbacks will be called mainly from a loop iteration).
93 /// <para>Since EFL 1.23.</para>
89 /// </summary> 94 /// </summary>
90 public Promise(CancelCb cancelCb = null) 95 public Promise(CancelCb cancelCb = null)
91 { 96 {
@@ -133,20 +138,26 @@ public class Promise : IDisposable
133 handle.Free(); 138 handle.Free();
134 } 139 }
135 140
136 /// <summary>Dispose this promise, causing its cancellation if it isn't already fulfilled.</summary> 141 /// <summary>Dispose this promise, causing its cancellation if it isn't already fulfilled.
142 /// <para>Since EFL 1.23.</para>
143 /// </summary>
137 public void Dispose() 144 public void Dispose()
138 { 145 {
139 Dispose(true); 146 Dispose(true);
140 GC.SuppressFinalize(this); 147 GC.SuppressFinalize(this);
141 } 148 }
142 149
143 /// <summary>Finalizer to be called from the Garbage Collector.</summary> 150 /// <summary>Finalizer to be called from the Garbage Collector.
151 /// <para>Since EFL 1.23.</para>
152 /// </summary>
144 ~Promise() 153 ~Promise()
145 { 154 {
146 Dispose(false); 155 Dispose(false);
147 } 156 }
148 157
149 /// <summary>Disposes of this wrapper, rejecting the native promise with <see cref="Eina.Error.ECANCELED"/></summary> 158 /// <summary>Disposes of this wrapper, rejecting the native promise with <see cref="Eina.Error.ECANCELED"/>.
159 /// <para>Since EFL 1.23.</para>
160 /// </summary>
150 /// <param name="disposing">True if this was called from <see cref="Dispose()"/> public method. False if 161 /// <param name="disposing">True if this was called from <see cref="Dispose()"/> public method. False if
151 /// called from the C# finalizer.</param> 162 /// called from the C# finalizer.</param>
152 protected virtual void Dispose(bool disposing) 163 protected virtual void Dispose(bool disposing)
@@ -176,7 +187,8 @@ public class Promise : IDisposable
176 /// <summary> 187 /// <summary>
177 /// Fulfills a promise with the given value. 188 /// Fulfills a promise with the given value.
178 /// 189 ///
179 /// This will make all futures attached to it to be called with the given value as payload. 190 /// <para>This will make all futures attached to it to be called with the given value as payload.</para>
191 /// <para>Since EFL 1.23.</para>
180 /// </summary> 192 /// </summary>
181 public void Resolve(Eina.Value value) 193 public void Resolve(Eina.Value value)
182 { 194 {
@@ -193,8 +205,9 @@ public class Promise : IDisposable
193 /// <summary> 205 /// <summary>
194 /// Rejects a promise. 206 /// Rejects a promise.
195 /// 207 ///
196 /// The future chain attached to this promise will be called with an Eina.Value of type 208 /// <para>The future chain attached to this promise will be called with an Eina.Value of type
197 /// Eina.ValueType.Error and payload Eina.Error.ECANCELED. 209 /// <see cref="Eina.ValueType.Error" /> and payload <see cref="Eina.Error.ECANCELED" />.</para>
210 /// <para>Since EFL 1.23.</para>
198 /// </summary> 211 /// </summary>
199 public void Reject(Eina.Error reason) 212 public void Reject(Eina.Error reason)
200 { 213 {
@@ -207,17 +220,19 @@ public class Promise : IDisposable
207/// <summary> 220/// <summary>
208/// Futures are the structures holding the callbacks to be notified of a promise fullfillment 221/// Futures are the structures holding the callbacks to be notified of a promise fullfillment
209/// or cancellation. 222/// or cancellation.
223/// <para>Since EFL 1.23.</para>
210/// </summary> 224/// </summary>
211public class Future 225public class Future
212{ 226{
213 /// <summary> 227 /// <summary>
214 /// Callback attached to a future and to be called when resolving/rejecting a promise. 228 /// Callback attached to a future and to be called when resolving/rejecting a promise.
215 /// 229 ///
216 /// The Eina.Value as argument can come with an Eina.Error.ECANCELED as payload if the 230 /// <para>The Eina.Value as argument can come with an <see cref="Eina.Error.ECANCELED" /> as payload if the
217 /// promise/future was rejected/cancelled. 231 /// promise/future was rejected/cancelled.</para>
218 /// 232 ///
219 /// The return value usually is same as the argument, forwarded, but can be changed in 233 /// <para>The return value usually is same as the argument, forwarded, but can be changed in
220 /// case were the chain act as a transforming pipeline. 234 /// case were the chain act as a transforming pipeline.</para>
235 /// <para>Since EFL 1.23.</para>
221 /// </summary> 236 /// </summary>
222 public delegate Eina.Value ResolvedCb(Eina.Value value); 237 public delegate Eina.Value ResolvedCb(Eina.Value value);
223 238
@@ -225,7 +240,9 @@ public class Future
225 240
226 /// <summary> 241 /// <summary>
227 /// Creates a Future from a native pointer. 242 /// Creates a Future from a native pointer.
243 /// <para>Since EFL 1.23.</para>
228 /// </summary> 244 /// </summary>
245 [EditorBrowsable(EditorBrowsableState.Never)]
229 public Future(IntPtr handle) 246 public Future(IntPtr handle)
230 { 247 {
231 handle = ThenRaw(handle, (Eina.Value value) => 248 handle = ThenRaw(handle, (Eina.Value value) =>
@@ -239,9 +256,13 @@ public class Future
239 /// <summary> 256 /// <summary>
240 /// Creates a Future attached to the given Promise. 257 /// Creates a Future attached to the given Promise.
241 /// 258 ///
242 /// Optionally a resolved callback may be provided. If so, it will be chained 259 /// <para>Optionally a resolved callback may be provided. If so, it will be chained
243 /// before the returned future. 260 /// before the returned future.</para>
261 /// <para>Since EFL 1.23.</para>
244 /// </summary> 262 /// </summary>
263 /// <param name="promise">The <see cref="Eina.Promise" /> which rejection or resolution will cause
264 /// the future to trigger.</param>
265 /// <param name="cb">The callback to be called when the attached promise resolves.</param>
245 public Future(Promise promise, ResolvedCb cb = null) 266 public Future(Promise promise, ResolvedCb cb = null)
246 { 267 {
247 IntPtr intermediate = eina_future_new(promise.Handle); 268 IntPtr intermediate = eina_future_new(promise.Handle);
@@ -268,8 +289,9 @@ public class Future
268 /// <summary> 289 /// <summary>
269 /// Cancels this future and the chain it belongs to, along with the promise linked against it. 290 /// Cancels this future and the chain it belongs to, along with the promise linked against it.
270 /// 291 ///
271 /// The callbacks will still be called with Eina.Error.ECANCELED as payload. The promise cancellation 292 /// <para>The callbacks will still be called with <see cref="Eina.Error.ECANCELED" /> as payload. The promise cancellation
272 /// callback will also be called if present. 293 /// callback will also be called if present.</para>
294 /// <para>Since EFL 1.23.</para>
273 /// </summary> 295 /// </summary>
274 public void Cancel() 296 public void Cancel()
275 { 297 {
@@ -280,12 +302,15 @@ public class Future
280 /// <summary> 302 /// <summary>
281 /// Creates a new future to be called after this one. 303 /// Creates a new future to be called after this one.
282 /// 304 ///
283 /// Once the promise this future is attached to resolves, the callbacks on the chain 305 /// <para>Once the promise this future is attached to resolves, the callbacks on the chain
284 /// are called in the order they were chained. 306 /// are called in the order they were chained.</para>
285 /// 307 ///
286 /// CAUTION: Calling Then() on a future that had it called before will replace the previous chain 308 /// <para>CAUTION: Calling Then() on a future that had it called before will replace the previous chain
287 /// from this point on. 309 /// from this point on.</para>
310 /// <para>Since EFL 1.23.</para>
288 /// </summary> 311 /// </summary>
312 /// <param name="cb">The callback to be called when this future is resolved.</param>
313 /// <returns>A new future in the chain after registering the callback.</returns>
289 public Future Then(ResolvedCb cb) 314 public Future Then(ResolvedCb cb)
290 { 315 {
291 SanityChecks(); 316 SanityChecks();
@@ -332,7 +357,10 @@ public class Future
332 /// 357 ///
333 /// It is just syntatic sugar for sequential Then() calls, without creating intermediate 358 /// It is just syntatic sugar for sequential Then() calls, without creating intermediate
334 /// futures explicitly. 359 /// futures explicitly.
360 /// <para>Since EFL 1.23.</para>
335 /// </summary> 361 /// </summary>
362 /// <param name="cbs">An enumerable with the callbacks to be chained together.</param>
363 /// <returns>The future representing the chain.</returns>
336 public Future Chain(IEnumerable<ResolvedCb> cbs) 364 public Future Chain(IEnumerable<ResolvedCb> cbs)
337 { 365 {
338 SanityChecks(); 366 SanityChecks();
@@ -375,6 +403,7 @@ public class Future
375 403
376/// <summary>Custom marshaler to convert between managed and native <see cref="Eina.Future"/>. 404/// <summary>Custom marshaler to convert between managed and native <see cref="Eina.Future"/>.
377/// Internal usage in generated code.</summary> 405/// Internal usage in generated code.</summary>
406[EditorBrowsable(EditorBrowsableState.Never)]
378public class FutureMarshaler : ICustomMarshaler 407public class FutureMarshaler : ICustomMarshaler
379{ 408{
380 409