Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 1 | """Abstract Protocol class.""" |
| 2 | |
Guido van Rossum | ac97bf4 | 2013-12-20 14:16:21 -0800 | [diff] [blame] | 3 | __all__ = ['BaseProtocol', 'Protocol', 'DatagramProtocol', |
| 4 | 'SubprocessProtocol'] |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 5 | |
| 6 | |
| 7 | class BaseProtocol: |
Guido van Rossum | 9204af4 | 2013-11-30 15:35:42 -0800 | [diff] [blame] | 8 | """Common base class for protocol interfaces. |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 9 | |
| 10 | Usually user implements protocols that derived from BaseProtocol |
| 11 | like Protocol or ProcessProtocol. |
| 12 | |
| 13 | The only case when BaseProtocol should be implemented directly is |
| 14 | write-only transport like write pipe |
| 15 | """ |
| 16 | |
| 17 | def connection_made(self, transport): |
| 18 | """Called when a connection is made. |
| 19 | |
| 20 | The argument is the transport representing the pipe connection. |
| 21 | To receive data, wait for data_received() calls. |
| 22 | When the connection is closed, connection_lost() is called. |
| 23 | """ |
| 24 | |
| 25 | def connection_lost(self, exc): |
| 26 | """Called when the connection is lost or closed. |
| 27 | |
| 28 | The argument is an exception object or None (the latter |
| 29 | meaning a regular EOF is received or the connection was |
| 30 | aborted or closed). |
| 31 | """ |
| 32 | |
Guido van Rossum | 355491d | 2013-10-18 15:17:11 -0700 | [diff] [blame] | 33 | def pause_writing(self): |
| 34 | """Called when the transport's buffer goes over the high-water mark. |
| 35 | |
| 36 | Pause and resume calls are paired -- pause_writing() is called |
| 37 | once when the buffer goes strictly over the high-water mark |
| 38 | (even if subsequent writes increases the buffer size even |
| 39 | more), and eventually resume_writing() is called once when the |
| 40 | buffer size reaches the low-water mark. |
| 41 | |
| 42 | Note that if the buffer size equals the high-water mark, |
| 43 | pause_writing() is not called -- it must go strictly over. |
| 44 | Conversely, resume_writing() is called when the buffer size is |
| 45 | equal or lower than the low-water mark. These end conditions |
| 46 | are important to ensure that things go as expected when either |
| 47 | mark is zero. |
| 48 | |
| 49 | NOTE: This is the only Protocol callback that is not called |
| 50 | through EventLoop.call_soon() -- if it were, it would have no |
| 51 | effect when it's most needed (when the app keeps writing |
| 52 | without yielding until pause_writing() is called). |
| 53 | """ |
| 54 | |
| 55 | def resume_writing(self): |
| 56 | """Called when the transport's buffer drains below the low-water mark. |
| 57 | |
| 58 | See pause_writing() for details. |
| 59 | """ |
| 60 | |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 61 | |
| 62 | class Protocol(BaseProtocol): |
Guido van Rossum | 9204af4 | 2013-11-30 15:35:42 -0800 | [diff] [blame] | 63 | """Interface for stream protocol. |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 64 | |
| 65 | The user should implement this interface. They can inherit from |
| 66 | this class but don't need to. The implementations here do |
| 67 | nothing (they don't raise exceptions). |
| 68 | |
| 69 | When the user wants to requests a transport, they pass a protocol |
| 70 | factory to a utility function (e.g., EventLoop.create_connection()). |
| 71 | |
| 72 | When the connection is made successfully, connection_made() is |
| 73 | called with a suitable transport object. Then data_received() |
| 74 | will be called 0 or more times with data (bytes) received from the |
| 75 | transport; finally, connection_lost() will be called exactly once |
| 76 | with either an exception object or None as an argument. |
| 77 | |
| 78 | State machine of calls: |
| 79 | |
| 80 | start -> CM [-> DR*] [-> ER?] -> CL -> end |
Victor Stinner | 54a231d | 2015-01-29 13:33:15 +0100 | [diff] [blame] | 81 | |
| 82 | * CM: connection_made() |
| 83 | * DR: data_received() |
| 84 | * ER: eof_received() |
| 85 | * CL: connection_lost() |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 86 | """ |
| 87 | |
| 88 | def data_received(self, data): |
| 89 | """Called when some data is received. |
| 90 | |
| 91 | The argument is a bytes object. |
| 92 | """ |
| 93 | |
| 94 | def eof_received(self): |
| 95 | """Called when the other end calls write_eof() or equivalent. |
| 96 | |
| 97 | If this returns a false value (including None), the transport |
| 98 | will close itself. If it returns a true value, closing the |
| 99 | transport is up to the protocol. |
| 100 | """ |
| 101 | |
| 102 | |
| 103 | class DatagramProtocol(BaseProtocol): |
Guido van Rossum | 9204af4 | 2013-11-30 15:35:42 -0800 | [diff] [blame] | 104 | """Interface for datagram protocol.""" |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 105 | |
| 106 | def datagram_received(self, data, addr): |
| 107 | """Called when some datagram is received.""" |
| 108 | |
Guido van Rossum | 2335de7 | 2013-11-15 16:51:48 -0800 | [diff] [blame] | 109 | def error_received(self, exc): |
| 110 | """Called when a send or receive operation raises an OSError. |
| 111 | |
| 112 | (Other than BlockingIOError or InterruptedError.) |
| 113 | """ |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 114 | |
| 115 | |
| 116 | class SubprocessProtocol(BaseProtocol): |
Guido van Rossum | 9204af4 | 2013-11-30 15:35:42 -0800 | [diff] [blame] | 117 | """Interface for protocol for subprocess calls.""" |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 118 | |
| 119 | def pipe_data_received(self, fd, data): |
Guido van Rossum | 2335de7 | 2013-11-15 16:51:48 -0800 | [diff] [blame] | 120 | """Called when the subprocess writes data into stdout/stderr pipe. |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 121 | |
Yury Selivanov | dec1a45 | 2014-02-18 22:27:48 -0500 | [diff] [blame] | 122 | fd is int file descriptor. |
Guido van Rossum | 27b7c7e | 2013-10-17 13:40:50 -0700 | [diff] [blame] | 123 | data is bytes object. |
| 124 | """ |
| 125 | |
| 126 | def pipe_connection_lost(self, fd, exc): |
| 127 | """Called when a file descriptor associated with the child process is |
| 128 | closed. |
| 129 | |
| 130 | fd is the int file descriptor that was closed. |
| 131 | """ |
| 132 | |
| 133 | def process_exited(self): |
Guido van Rossum | 2335de7 | 2013-11-15 16:51:48 -0800 | [diff] [blame] | 134 | """Called when subprocess has exited.""" |