codekingpro/portable-devtools

1# Copyright 2015 gRPC authors.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#     http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14"""A Future interface.
15
16Python doesn't have a Future interface in its standard library. In the absence
17of such a standard, three separate, incompatible implementations
18(concurrent.futures.Future, ndb.Future, and asyncio.Future) have appeared. This
19interface attempts to be as compatible as possible with
20concurrent.futures.Future. From ndb.Future it adopts a traceback-object accessor
21method.
22
23Unlike the concrete and implemented Future classes listed above, the Future
24class defined in this module is an entirely abstract interface that anyone may
25implement and use.
26
27The one known incompatibility between this interface and the interface of
28concurrent.futures.Future is that this interface defines its own CancelledError
29and TimeoutError exceptions rather than raising the implementation-private
30concurrent.futures._base.CancelledError and the
31built-in-but-only-in-3.3-and-later TimeoutError.
32"""
33
34import abc
35
36
37class TimeoutError(Exception):
38    """Indicates that a particular call timed out."""
39
40
41class CancelledError(Exception):
42    """Indicates that the computation underlying a Future was cancelled."""
43
44
45class Future(abc.ABC):
46    """A representation of a computation in another control flow.
47
48    Computations represented by a Future may be yet to be begun, may be ongoing,
49    or may have already completed.
50    """
51
52    # NOTE(nathaniel): This isn't the return type that I would want to have if it
53    # were up to me. Were this interface being written from scratch, the return
54    # type of this method would probably be a sum type like:
55    #
56    # NOT_COMMENCED
57    # COMMENCED_AND_NOT_COMPLETED
58    # PARTIAL_RESULT<Partial_Result_Type>
59    # COMPLETED<Result_Type>
60    # UNCANCELLABLE
61    # NOT_IMMEDIATELY_DETERMINABLE
62    @abc.abstractmethod
63    def cancel(self):
64        """Attempts to cancel the computation.
65
66        This method does not block.
67
68        Returns:
69          True if the computation has not yet begun, will not be allowed to take
70            place, and determination of both was possible without blocking. False
71            under all other circumstances including but not limited to the
72            computation's already having begun, the computation's already having
73            finished, and the computation's having been scheduled for execution on a
74            remote system for which a determination of whether or not it commenced
75            before being cancelled cannot be made without blocking.
76        """
77        raise NotImplementedError()
78
79    # NOTE(nathaniel): Here too this isn't the return type that I'd want this
80    # method to have if it were up to me. I think I'd go with another sum type
81    # like:
82    #
83    # NOT_CANCELLED (this object's cancel method hasn't been called)
84    # NOT_COMMENCED
85    # COMMENCED_AND_NOT_COMPLETED
86    # PARTIAL_RESULT<Partial_Result_Type>
87    # COMPLETED<Result_Type>
88    # UNCANCELLABLE
89    # NOT_IMMEDIATELY_DETERMINABLE
90    #
91    # Notice how giving the cancel method the right semantics obviates most
92    # reasons for this method to exist.
93    @abc.abstractmethod
94    def cancelled(self):
95        """Describes whether the computation was cancelled.
96
97        This method does not block.
98
99        Returns:
100          True if the computation was cancelled any time before its result became
101            immediately available. False under all other circumstances including but
102            not limited to this object's cancel method not having been called and
103            the computation's result having become immediately available.
104        """
105        raise NotImplementedError()
106
107    @abc.abstractmethod
108    def running(self):
109        """Describes whether the computation is taking place.
110
111        This method does not block.
112
113        Returns:
114          True if the computation is scheduled to take place in the future or is
115            taking place now, or False if the computation took place in the past or
116            was cancelled.
117        """
118        raise NotImplementedError()
119
120    # NOTE(nathaniel): These aren't quite the semantics I'd like here either. I
121    # would rather this only returned True in cases in which the underlying
122    # computation completed successfully. A computation's having been cancelled
123    # conflicts with considering that computation "done".
124    @abc.abstractmethod
125    def done(self):
126        """Describes whether the computation has taken place.
127
128        This method does not block.
129
130        Returns:
131          True if the computation is known to have either completed or have been
132            unscheduled or interrupted. False if the computation may possibly be
133            executing or scheduled to execute later.
134        """
135        raise NotImplementedError()
136
137    @abc.abstractmethod
138    def result(self, timeout=None):
139        """Accesses the outcome of the computation or raises its exception.
140
141        This method may return immediately or may block.
142
143        Args:
144          timeout: The length of time in seconds to wait for the computation to
145            finish or be cancelled, or None if this method should block until the
146            computation has finished or is cancelled no matter how long that takes.
147
148        Returns:
149          The return value of the computation.
150
151        Raises:
152          TimeoutError: If a timeout value is passed and the computation does not
153            terminate within the allotted time.
154          CancelledError: If the computation was cancelled.
155          Exception: If the computation raised an exception, this call will raise
156            the same exception.
157        """
158        raise NotImplementedError()
159
160    @abc.abstractmethod
161    def exception(self, timeout=None):
162        """Return the exception raised by the computation.
163
164        This method may return immediately or may block.
165
166        Args:
167          timeout: The length of time in seconds to wait for the computation to
168            terminate or be cancelled, or None if this method should block until
169            the computation is terminated or is cancelled no matter how long that
170            takes.
171
172        Returns:
173          The exception raised by the computation, or None if the computation did
174            not raise an exception.
175
176        Raises:
177          TimeoutError: If a timeout value is passed and the computation does not
178            terminate within the allotted time.
179          CancelledError: If the computation was cancelled.
180        """
181        raise NotImplementedError()
182
183    @abc.abstractmethod
184    def traceback(self, timeout=None):
185        """Access the traceback of the exception raised by the computation.
186
187        This method may return immediately or may block.
188
189        Args:
190          timeout: The length of time in seconds to wait for the computation to
191            terminate or be cancelled, or None if this method should block until
192            the computation is terminated or is cancelled no matter how long that
193            takes.
194
195        Returns:
196          The traceback of the exception raised by the computation, or None if the
197            computation did not raise an exception.
198
199        Raises:
200          TimeoutError: If a timeout value is passed and the computation does not
201            terminate within the allotted time.
202          CancelledError: If the computation was cancelled.
203        """
204        raise NotImplementedError()
205
206    @abc.abstractmethod
207    def add_done_callback(self, fn):
208        """Adds a function to be called at completion of the computation.
209
210        The callback will be passed this Future object describing the outcome of
211        the computation.
212
213        If the computation has already completed, the callback will be called
214        immediately.
215
216        Args:
217          fn: A callable taking this Future object as its single parameter.
218        """
219        raise NotImplementedError()
220