annotate Implab/IPromise.cs @ 136:e9e7940c7d98 v2

shared locks + tests
author cin
date Mon, 16 Feb 2015 01:14:09 +0300
parents 2573b562e328
children f75cfa58e3d4
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
1 using System;
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
2 using System.Collections.Generic;
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
3 using System.Linq;
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
4 using System.Text;
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
5
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
6 namespace Implab {
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
7 public interface IPromise: ICancellable {
26
f0bf98e4d22c refactoring
cin
parents: 25
diff changeset
8
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
9 /// <summary>
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
10 /// Тип результата, получаемого через данное обещание.
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
11 /// </summary>
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
12 Type PromiseType { get; }
25
9bf5b23650c9 refactoring
cin
parents: 19
diff changeset
13
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
14 /// <summary>
99
8ddf1648eca4 fixed TransientPromiseException handling
cin
parents: 96
diff changeset
15 /// Обещание является выполненым, либо успешно, либо с ошибкой, либо отменено.
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
16 /// </summary>
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
17 bool IsResolved { get; }
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
18
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
19 /// <summary>
c4140283575c minor fixes
cin
parents: 66
diff changeset
20 /// Обещание было отменено.
c4140283575c minor fixes
cin
parents: 66
diff changeset
21 /// </summary>
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
22 bool IsCancelled { get; }
25
9bf5b23650c9 refactoring
cin
parents: 19
diff changeset
23
119
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
24 /// <summary>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
25 /// Creates a new promise dependend on the current one and resolved on
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
26 /// executing the specified handlers.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
27 /// </summary>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
28 /// <param name="success">The handler called on the successful promise completion.</param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
29 /// <param name="error">The handler is called if an error while completing the promise occurred.</param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
30 /// <param name="cancel">The handler is called in case of promise cancellation.</param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
31 /// <returns>The newly created dependant promise.</returns>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
32 /// <remarks>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
33 /// <para>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
34 /// If the success handler is specified the dependend promise will be resolved after the handler is
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
35 /// executed and the dependent promise will be linked to the current one, i.e. the cancellation
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
36 /// of the dependent property will lead to the cancellation of the current promise. If the
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
37 /// success handler isn't specified the dependent promise will not be linked to and
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
38 /// will not be resolved after the successfull resolution of the current one.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
39 /// </para>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
40 /// <para>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
41 /// When the error handler is specified, the exception raised during the current promise completion
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
42 /// will be passed to it as the parameter. If the error handler returns without raising an
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
43 /// exception then the dependant promise will be resolved successfully, otherwise the exception
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
44 /// raised by the handler will be transmitted to the dependent promise. If the handler wants
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
45 /// to passthrough the original exception it needs to wrap the exception with
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
46 /// the <see cref="PromiseTransientException"/>.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
47 /// </para>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
48 /// <para>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
49 /// If the cancelation handler is specified and the current promise is cancelled then the dependent
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
50 /// promise will be resolved after the handler is executed. If the cancelation hendler raises the
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
51 /// exception it will be passed to the dependent promise.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
52 /// </para>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
53 /// </remarks>
101
279e226dffdd code cleanup
cin
parents: 99
diff changeset
54 IPromise Then(Action success, Action<Exception> error, Action cancel);
279e226dffdd code cleanup
cin
parents: 99
diff changeset
55 IPromise Then(Action success, Action<Exception> error);
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
56 IPromise Then(Action success);
75
4439140706d0 major refactoring, added tasks support
cin
parents: 74
diff changeset
57
119
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
58 IPromise Chain(Func<IPromise> chained, Func<Exception, IPromise> error, Func<IPromise> cancel);
101
279e226dffdd code cleanup
cin
parents: 99
diff changeset
59 IPromise Chain(Func<IPromise> chained, Func<Exception, IPromise> error);
96
daffa72a1cec Added the chaining method to the non-generic IPromise
cin
parents: 76
diff changeset
60 IPromise Chain(Func<IPromise> chained);
daffa72a1cec Added the chaining method to the non-generic IPromise
cin
parents: 76
diff changeset
61
75
4439140706d0 major refactoring, added tasks support
cin
parents: 74
diff changeset
62 /// <summary>
119
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
63 /// Adds specified listeners to the current promise.
75
4439140706d0 major refactoring, added tasks support
cin
parents: 74
diff changeset
64 /// </summary>
119
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
65 /// <param name="success">The handler called on the successful promise completion.</param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
66 /// <param name="error">The handler is called if an error while completing the promise occurred.</param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
67 /// <param name="cancel">The handler is called in case of promise cancellation.</param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
68 /// <returns>The current promise.</returns>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
69 IPromise On(Action success, Action<Exception> error, Action cancel);
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
70 IPromise On(Action success, Action<Exception> error);
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
71 IPromise On(Action success);
75
4439140706d0 major refactoring, added tasks support
cin
parents: 74
diff changeset
72
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
73 /// <summary>
119
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
74 /// Adds specified listeners to the current promise.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
75 /// </summary>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
76 /// <param name="handler">The handler called on the specified events.</param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
77 /// <param name = "events">The combination of flags denoting the events for which the
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
78 /// handler shoud be called.</param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
79 /// <returns>The current promise.</returns>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
80 IPromise On(Action handler, PromiseEventType events);
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
81
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
82 /// <summary>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
83 /// Adds the specified error handler to the current promise
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
84 /// and creates the new dependant promise.
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
85 /// </summary>
119
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
86 /// <param name="error">
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
87 /// The error handler. If the error handler returns without
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
88 /// an error the dependant promise will be successfully resolved.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
89 /// </param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
90 /// <returns>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
91 /// The new dependant promise which will be resolved after the error
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
92 /// handler is executed.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
93 /// </returns>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
94 /// <remarks>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
95 /// The successfull result of the current promise will be ignored.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
96 /// </remarks>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
97 IPromise Error(Action<Exception> error);
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
98
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
99 /// <summary>
119
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
100 /// Adds the specified cncellation handler to the current promise
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
101 /// and creates the new dependant promise.
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
102 /// </summary>
119
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
103 /// <returns>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
104 /// The new dependant promise which will be resolved after the cancellation
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
105 /// handler is executed.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
106 /// </returns>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
107 /// <param name="handler">
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
108 /// The cancellation handler.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
109 /// </param>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
110 /// <remarks>
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
111 /// If the cancellation handler is executed without an error the dependent
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
112 /// promise will be successfully resolved, otherwise the raised exception
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
113 /// will be passed to the dependant promise. The successful result of the
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
114 /// current promise will be ignored.
2573b562e328 Promises rewritten, added improved version of AsyncQueue
cin
parents: 104
diff changeset
115 /// </remarks>
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
116 IPromise Cancelled(Action handler);
7
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
117
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
118 /// <summary>
c4140283575c minor fixes
cin
parents: 66
diff changeset
119 /// Преобразует результат обещания к заданному типу и возвращает новое обещание.
c4140283575c minor fixes
cin
parents: 66
diff changeset
120 /// </summary>
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
121 IPromise<T> Cast<T>();
26
f0bf98e4d22c refactoring
cin
parents: 25
diff changeset
122
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
123 /// <summary>
c4140283575c minor fixes
cin
parents: 66
diff changeset
124 /// Синхронизирует текущий поток с обещанием.
c4140283575c minor fixes
cin
parents: 66
diff changeset
125 /// </summary>
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
126 void Join();
74
c4140283575c minor fixes
cin
parents: 66
diff changeset
127 /// <summary>
c4140283575c minor fixes
cin
parents: 66
diff changeset
128 /// Синхронизирует текущий поток с обещанием.
c4140283575c minor fixes
cin
parents: 66
diff changeset
129 /// </summary>
c4140283575c minor fixes
cin
parents: 66
diff changeset
130 /// <param name="timeout">Время ожидания, по его истечению возникнет исключение.</param>
c4140283575c minor fixes
cin
parents: 66
diff changeset
131 /// <exception cref="TimeoutException">Превышено время ожидания.</exception>
66
790e8a997d30 Refactoring
cin
parents: 33
diff changeset
132 void Join(int timeout);
7
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
133
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
134 }
7ea9363fef6c inital progress handling
cin
parents:
diff changeset
135 }