[urisagit/Stem.git] / Design / asyncio_notes

		       Stem::AsyncIO Design Notes

The Stem::AsyncIO module provides a buffered I/O interface to sockets
and process handles. It is used by a variety of modules such as
Stem::Proc, Stem::SockMsg, Stem::Portal::Stream to do the common
function of doing their buffered I/O.

The constructor takes an owner object and up to 3 handles: input, output
and stderr (for processes). The input and stderr handles are monitored
with read events and when data is available, it is read and a callback
is made to the owner object with the data as its argument.

The write handle is fully buffered and the module provides non-blocking
asynchronous output to it. Data to be sent to the handle is passed in
with the write method. If there is any output data buffered, a write
event monitors the handle and triggers a callback when data can be
written to it. The callback writes as much data as possible to the write
handle.

If the read or stderr handle is being used and it is closed (the socket
is disconnected or the process exits), this is detected and a callback
to the owner object is made.

This module is only used internally and should not be configured.
Commit	Line	Data
4536f655	1	Stem::AsyncIO Design Notes
	2
	3	The Stem::AsyncIO module provides a buffered I/O interface to sockets
	4	and process handles. It is used by a variety of modules such as
	5	Stem::Proc, Stem::SockMsg, Stem::Portal::Stream to do the common
	6	function of doing their buffered I/O.
	7
	8	The constructor takes an owner object and up to 3 handles: input, output
	9	and stderr (for processes). The input and stderr handles are monitored
	10	with read events and when data is available, it is read and a callback
	11	is made to the owner object with the data as its argument.
	12
	13	The write handle is fully buffered and the module provides non-blocking
	14	asynchronous output to it. Data to be sent to the handle is passed in
	15	with the write method. If there is any output data buffered, a write
	16	event monitors the handle and triggers a callback when data can be
	17	written to it. The callback writes as much data as possible to the write
	18	handle.
	19
	20	If the read or stderr handle is being used and it is closed (the socket
	21	is disconnected or the process exits), this is detected and a callback
	22	to the owner object is made.
	23
	24	This module is only used internally and should not be configured.