kimcinoo
/
efl
forked from enlightenment/efl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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
This commit is contained in:
Lauro Moura 2019-10-15 10:10:53 -03:00 committed by Mike Blumenkrantz
parent 1d3d5ec8ca
commit bf1f71a7a7
1 changed files with 49 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
src/bindings/mono/eina_mono/eina_promises.cs
View File

@ -2,6 +2,7 @@ using System;
using System.Runtime.InteropServices; using System.Runtime.InteropServices;
using System.Collections.Generic; using System.Collections.Generic;
using System.Linq; using System.Linq;
using System.ComponentModel;
using static Eina.EinaNative.PromiseNativeMethods; using static Eina.EinaNative.PromiseNativeMethods;
@ -12,6 +13,7 @@ namespace Eina
namespace EinaNative namespace EinaNative
{ {
[EditorBrowsable(EditorBrowsableState.Never)]
static internal class PromiseNativeMethods static internal class PromiseNativeMethods
{ {
internal delegate void Promise_Cancel_Cb(IntPtr data, IntPtr dead); internal delegate void Promise_Cancel_Cb(IntPtr data, IntPtr dead);
@ -71,14 +73,16 @@ static internal class PromiseNativeMethods
/// ///
/// With a Promise you can attach futures to it, which will be used to notify of the value being available. /// With a Promise you can attach futures to it, which will be used to notify of the value being available.
/// ///
/// Since Efl 1.23. /// <para>Since Efl 1.23.</para>
/// </summary> /// </summary>
public class Promise : IDisposable public class Promise : IDisposable
{ {
internal IntPtr Handle; internal IntPtr Handle;
private GCHandle CleanupHandle; private GCHandle CleanupHandle;
/// <summary>Delegate for functions that will be called upon a promise cancellation.</summary> /// <summary>Delegate for functions that will be called upon a promise cancellation.
/// <para>Since EFL 1.23.</para>
/// </summary>
public delegate void CancelCb(); public delegate void CancelCb();
/// <summary> /// <summary>
@ -86,6 +90,7 @@ public class Promise : IDisposable
/// ///
/// Currently, creating a promise directly uses the Main Loop scheduler the source of notifications (i.e. the /// Currently, creating a promise directly uses the Main Loop scheduler the source of notifications (i.e. the
/// future callbacks will be called mainly from a loop iteration). /// future callbacks will be called mainly from a loop iteration).
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
public Promise(CancelCb cancelCb = null) public Promise(CancelCb cancelCb = null)
{ {
@ -133,20 +138,26 @@ public class Promise : IDisposable
handle.Free(); handle.Free();
} }
/// <summary>Dispose this promise, causing its cancellation if it isn't already fulfilled.</summary> /// <summary>Dispose this promise, causing its cancellation if it isn't already fulfilled.
/// <para>Since EFL 1.23.</para>
/// </summary>
public void Dispose() public void Dispose()
{ {
Dispose(true); Dispose(true);
GC.SuppressFinalize(this); GC.SuppressFinalize(this);
} }
/// <summary>Finalizer to be called from the Garbage Collector.</summary> /// <summary>Finalizer to be called from the Garbage Collector.
/// <para>Since EFL 1.23.</para>
/// </summary>
~Promise() ~Promise()
{ {
Dispose(false); Dispose(false);
} }
/// <summary>Disposes of this wrapper, rejecting the native promise with <see cref="Eina.Error.ECANCELED"/></summary> /// <summary>Disposes of this wrapper, rejecting the native promise with <see cref="Eina.Error.ECANCELED"/>.
/// <para>Since EFL 1.23.</para>
/// </summary>
/// <param name="disposing">True if this was called from <see cref="Dispose()"/> public method. False if /// <param name="disposing">True if this was called from <see cref="Dispose()"/> public method. False if
/// called from the C# finalizer.</param> /// called from the C# finalizer.</param>
protected virtual void Dispose(bool disposing) protected virtual void Dispose(bool disposing)
@ -176,7 +187,8 @@ public class Promise : IDisposable
/// <summary> /// <summary>
/// Fulfills a promise with the given value. /// Fulfills a promise with the given value.
/// ///
/// This will make all futures attached to it to be called with the given value as payload. /// <para>This will make all futures attached to it to be called with the given value as payload.</para>
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
public void Resolve(Eina.Value value) public void Resolve(Eina.Value value)
{ {
@ -193,8 +205,9 @@ public class Promise : IDisposable
/// <summary> /// <summary>
/// Rejects a promise. /// Rejects a promise.
/// ///
/// The future chain attached to this promise will be called with an Eina.Value of type /// <para>The future chain attached to this promise will be called with an Eina.Value of type
/// Eina.ValueType.Error and payload Eina.Error.ECANCELED. /// <see cref="Eina.ValueType.Error" /> and payload <see cref="Eina.Error.ECANCELED" />.</para>
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
public void Reject(Eina.Error reason) public void Reject(Eina.Error reason)
{ {
@ -207,17 +220,19 @@ public class Promise : IDisposable
/// <summary> /// <summary>
/// Futures are the structures holding the callbacks to be notified of a promise fullfillment /// Futures are the structures holding the callbacks to be notified of a promise fullfillment
/// or cancellation. /// or cancellation.
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
public class Future public class Future
{ {
/// <summary> /// <summary>
/// Callback attached to a future and to be called when resolving/rejecting a promise. /// Callback attached to a future and to be called when resolving/rejecting a promise.
/// ///
/// The Eina.Value as argument can come with an Eina.Error.ECANCELED as payload if the /// <para>The Eina.Value as argument can come with an <see cref="Eina.Error.ECANCELED" /> as payload if the
/// promise/future was rejected/cancelled. /// promise/future was rejected/cancelled.</para>
/// ///
/// The return value usually is same as the argument, forwarded, but can be changed in /// <para>The return value usually is same as the argument, forwarded, but can be changed in
/// case were the chain act as a transforming pipeline. /// case were the chain act as a transforming pipeline.</para>
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
public delegate Eina.Value ResolvedCb(Eina.Value value); public delegate Eina.Value ResolvedCb(Eina.Value value);
@ -225,7 +240,9 @@ public class Future
/// <summary> /// <summary>
/// Creates a Future from a native pointer. /// Creates a Future from a native pointer.
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
[EditorBrowsable(EditorBrowsableState.Never)]
public Future(IntPtr handle) public Future(IntPtr handle)
{ {
handle = ThenRaw(handle, (Eina.Value value) => handle = ThenRaw(handle, (Eina.Value value) =>
@ -239,9 +256,13 @@ public class Future
/// <summary> /// <summary>
/// Creates a Future attached to the given Promise. /// Creates a Future attached to the given Promise.
/// ///
/// Optionally a resolved callback may be provided. If so, it will be chained /// <para>Optionally a resolved callback may be provided. If so, it will be chained
/// before the returned future. /// before the returned future.</para>
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
/// <param name="promise">The <see cref="Eina.Promise" /> which rejection or resolution will cause
/// the future to trigger.</param>
/// <param name="cb">The callback to be called when the attached promise resolves.</param>
public Future(Promise promise, ResolvedCb cb = null) public Future(Promise promise, ResolvedCb cb = null)
{ {
IntPtr intermediate = eina_future_new(promise.Handle); IntPtr intermediate = eina_future_new(promise.Handle);
@ -268,8 +289,9 @@ public class Future
/// <summary> /// <summary>
/// Cancels this future and the chain it belongs to, along with the promise linked against it. /// Cancels this future and the chain it belongs to, along with the promise linked against it.
/// ///
/// The callbacks will still be called with Eina.Error.ECANCELED as payload. The promise cancellation /// <para>The callbacks will still be called with <see cref="Eina.Error.ECANCELED" /> as payload. The promise cancellation
/// callback will also be called if present. /// callback will also be called if present.</para>
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
public void Cancel() public void Cancel()
{ {
@ -280,12 +302,15 @@ public class Future
/// <summary> /// <summary>
/// Creates a new future to be called after this one. /// Creates a new future to be called after this one.
/// ///
/// Once the promise this future is attached to resolves, the callbacks on the chain /// <para>Once the promise this future is attached to resolves, the callbacks on the chain
/// are called in the order they were chained. /// are called in the order they were chained.</para>
/// ///
/// CAUTION: Calling Then() on a future that had it called before will replace the previous chain /// <para>CAUTION: Calling Then() on a future that had it called before will replace the previous chain
/// from this point on. /// from this point on.</para>
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
/// <param name="cb">The callback to be called when this future is resolved.</param>
/// <returns>A new future in the chain after registering the callback.</returns>
public Future Then(ResolvedCb cb) public Future Then(ResolvedCb cb)
{ {
SanityChecks(); SanityChecks();
@ -332,7 +357,10 @@ public class Future
/// ///
/// It is just syntatic sugar for sequential Then() calls, without creating intermediate /// It is just syntatic sugar for sequential Then() calls, without creating intermediate
/// futures explicitly. /// futures explicitly.
/// <para>Since EFL 1.23.</para>
/// </summary> /// </summary>
/// <param name="cbs">An enumerable with the callbacks to be chained together.</param>
/// <returns>The future representing the chain.</returns>
public Future Chain(IEnumerable<ResolvedCb> cbs) public Future Chain(IEnumerable<ResolvedCb> cbs)
{ {
SanityChecks(); SanityChecks();
@ -375,6 +403,7 @@ public class Future
/// <summary>Custom marshaler to convert between managed and native <see cref="Eina.Future"/>. /// <summary>Custom marshaler to convert between managed and native <see cref="Eina.Future"/>.
/// Internal usage in generated code.</summary> /// Internal usage in generated code.</summary>
[EditorBrowsable(EditorBrowsableState.Never)]
public class FutureMarshaler : ICustomMarshaler public class FutureMarshaler : ICustomMarshaler
{ {