Documentation for pulsar 0.9.2. For development docs, go here.
This part of the pulsar API is about classes responsible for
implementing the Protocol/Transport paradigm. They are based on
asyncio.Protocol
and asyncio.DatagramProtocol
classes.
pulsar.async.protocols.
PulsarProtocol
(loop=None, session=1, producer=None, **kw)[source]¶A mixin class for both Protocol
and
DatagramProtocol
.
A PulsarProtocol
is an EventHandler
which has
two one time events:
connection_made
connection_lost
session
¶Connection session number.
Passed during initialisation by the producer
.
Usually an integer representing the number of separate connections
the producer has processed at the time it created this
Protocol
.
transport
¶The transport for this protocol.
Available once the connection_made()
is called.
pulsar.async.protocols.
Connection
(consumer_factory=None, timeout=None, low_limit=None, high_limit=None, **kw)[source]¶A FlowControl
to handle multiple TCP requests/responses.
It is a class which acts as bridge between a
transport and a ProtocolConsumer
.
It routes data arriving from the transport to the
current_consumer()
.
_consumer_factory
¶A factory of ProtocolConsumer
.
_processed
¶number of separate requests processed.
current_consumer
()[source]¶The ProtocolConsumer
currently handling incoming data.
This instance will receive data when this connection get data
from the transport
via the data_received()
method.
data_received
(data)[source]¶Delegates handling of data to the current_consumer()
.
Once done set a timeout for idle connections when a
timeout
is a positive number (of seconds).
upgrade
(consumer_factory)[source]¶Upgrade the _consumer_factory()
callable.
This method can be used when the protocol specification changes during a response (an example is a WebSocket request/response, or HTTP tunneling).
This method adds a post_request
callback to the
current_consumer()
to build a new consumer with the new
_consumer_factory()
.
Parameters: | consumer_factory – the new consumer factory (a callable accepting no parameters) |
---|---|
Returns: | None . |
pulsar.async.protocols.
ProtocolConsumer
(loop=None, one_time_events=None, many_times_events=None)[source]¶The consumer of data for a server or client Connection
.
It is responsible for receiving incoming data from an end point via the
Connection.data_received()
method, decoding (parsing) and,
possibly, writing back to the client or server via
the transport
attribute.
Note
For server consumers, data_received()
is the only method
to implement.
For client consumers, start_request()
should also be implemented.
A ProtocolConsumer
is a subclass of EventHandler
and it
has two default one time events:
pre_request
fired when the request is received (for servers) or
just before is sent (for clients).
This occurs just before the start_request()
method.post_request
fired when the request is done. The
on_finished
attribute is a shortcut for the post_request
OneTime
event and therefore can be used to wait for
the request to have received a full response (clients).In addition, it has two many times events:
data_received
fired when new data is received from the transport but
not yet processed (before the data_received()
method is invoked)data_processed
fired just after data has been consumed (after the
data_received()
method)Note
A useful example on how to use the data_received
event is
the wsgi proxy server.
connection
¶The Connection
of this consumer.
transport
¶The Transport
of this consumer
on_finished
¶The post_request
one time event.
connection_made
(connection)[source]¶Called by a Connection
when it starts using this consumer.
By default it does nothing.
data_received
(data)[source]¶Called when some data is received.
This method must be implemented by subclasses for both server and client consumers.
The argument is a bytes object.
start_request
()[source]¶Starts a new request.
Invoked by the start()
method to kick start the
request with remote server. For server ProtocolConsumer
this
method is not invoked at all.
For clients this method should be implemented and it is critical
method where errors caused by stale socket connections can arise.
This method should not be called directly. Use start()
instead. Typically one writes some data from the request
into the transport. Something like this:
self.transport.write(self.request.encode())
start
(request=None)[source]¶Starts processing the request for this protocol consumer.
There is no need to override this method,
implement start_request()
instead.
If either connection
or transport
are missing, a
RuntimeError
occurs.
For server side consumer, this method simply fires the pre_request
event.
connection_lost
(exc)[source]¶Called by the connection
when the transport is closed.
By default it calls the finished()
method. It can be overwritten
to handle the potential exception exc
.
write
(data)[source]¶Delegate writing to the underlying Connection
Return an empty tuple or a Future
Producers are factory of Protocol
with end-points.
They are used by both servers and clients classes.
pulsar.async.protocols.
Producer
(loop, protocol_factory=None, name=None, max_requests=None, logger=None)[source]¶An Abstract EventHandler
class for all producers of
socket (client and servers)
protocol_factory
= None¶A callable producing protocols.
The signature of the protocol factory callable must be:
protocol_factory(session, producer, **params)
requests_processed
¶Total number of requests processed.
create_protocol
(**kw)[source]¶Create a new protocol via the protocol_factory()
This method increase the count of sessions
and build
the protocol passing self
as the producer.
build_consumer
(consumer_factory)[source]¶Build a consumer for a protocol.
This method can be used by protocols which handle several requests,
for example the Connection
class.
Parameters: | consumer_factory – consumer factory to use. |
---|
pulsar.async.protocols.
TcpServer
(protocol_factory, loop, address=None, name=None, sockets=None, max_requests=None, keep_alive=None, logger=None)[source]¶A Producer
of server Connection
for TCP servers.
_server
¶A Server
managed by this Tcp wrapper.
Available once the start_serving()
method has returned.
address
¶Socket address of this server.
It is obtained from the first socket getsockname
method.
start_serving
(*args, **kwargs)[source]¶Start serving.
Parameters: |
|
---|---|
Returns: | a |
close
(*args, **kwargs)[source]¶Stop serving the Server.sockets
and close all
concurrent connections.
create_protocol
()[source]¶Override Producer.create_protocol()
.
Classes for the (user) datagram protocol. UDP uses a simple transmission model with a minimum of protocol mechanism.
pulsar.async.protocols.
DatagramServer
(protocol_factory, loop=None, address=None, name=None, sockets=None, max_requests=None, logger=None)[source]¶An Producer
for serving UDP sockets.
_transports
¶A list of DatagramTransport
.
Available once the create_endpoint()
method has returned.
pulsar.async.mixins.
FlowControl
(low_limit=None, high_limit=None, **kw)[source]¶A protocol mixin for flow control logic.
This implements the protocol methods pause_writing()
,
resume_writing()
.
pause_writing
()[source]¶Called by the transport when the buffer goes over the high-water mark
Successive calls to this method will fails unless
resume_writing()
is called first.
resume_writing
(exc=None)[source]¶Resume writing.
Successive calls to this method will fails unless
pause_writing()
is called first.
This section introduces classes implementing the transport/protocol paradigm
for clients with several connections to a remote TcpServer
.
pulsar.async.clients.
Pool
(creator, pool_size=10, loop=None, timeout=None, **kw)[source]¶An asynchronous pool of open connections.
Open connections are either in_use
or available
to be used. Available connection are placed in an asyncio.Queue
.
This class is not thread safe.
pool_size
¶The maximum number of open connections allowed.
If more connections are requested, the request is queued and a connection returned as soon as one becomes available.
in_use
¶The number of connections in use.
These connections are not available until they are released back to the pool.
available
¶Number of available connections in the pool.
pulsar.async.clients.
PoolConnection
(pool, connection)[source]¶A wrapper for a Connection
in a connection Pool
.
pool
¶The Pool
which created this PoolConnection
connection
¶The underlying socket connection.
close
(discard=False)[source]¶Close this pool connection by releasing the underlying
connection
back to the ;attr:pool.
detach
()[source]¶Remove the underlying connection
from the connection
pool
.