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