Asyncio

Please import all classes from namespace libchirp.asyncio, to make sure you get the right implementation.

from libchirp.asyncio import Chirp, Config, Loop, Message
libchirp.asyncio.Chirp(loop, config, ...) Runs chirp in a asyncio environment.
libchirp.asyncio.Message([cmsg]) Chirp message.

Example

async_echo.py

import asyncio
from libchirp.asyncio import Chirp, Config, Loop

class MyChirp(Chirp):
    async def handler(self, msg):
        print(msg.data)
        await self.send(msg)
        aio_loop.stop()

loop = Loop(); config = Config()
config.DISABLE_ENCRYPTION = True
# Workers are usually asynchronous
config.SYNCHRONOUS = False
aio_loop = asyncio.get_event_loop()
try:
    chirp = MyChirp(loop, config, aio_loop)
    try:
        aio_loop.run_forever()
    finally:
        chirp.stop()
finally:
    loop.stop()

For a sender see Example.

Chirp

class libchirp.asyncio.Chirp(loop, config, asyncio_loop)[source]

Bases: libchirp.ChirpBase

Runs chirp in a asyncio environment.

Messages are received via a handler and sending is await-able.

Subclass libchirp.asyncio.Chirp and implement handler().

Concurrency is achieved by sending multiple messages and waiting for results later. Use libchirp.queue.Message.identity as key to a dict, to match-up requests and answers.

See Exceptions.

Parameters:
handler(msg)[source]

Called when a message arrives.

Please implement this method.

If you don’t implement this chirp will release the message-slots regardless of the AUTO_RELEASE setting.

Parameters:msg (libchirp.asyncio.Message) – The message
identity()
loop

Get the libchirp.Loop used by the chirp instance.

Return type:Loop
request(msg, auto_release=True)[source]

Send a message and wait for an answer.

This method returns a libchirp.ChirpFutureAsync.

Returns a Future which you can await. The result will contain the answer to the message. If you don’t intend to consume the result use send() instead.

By default the message slot used by the response will released. If auto_release is False, you have to release the response-message.

Exceptions, threading and concurrency aspects are the same as send(). Issue: If a answer to request arrives after the timeout it will be delivered at normal message.

req = chirp.request(msg)
await req.send_result()
answer = await req
Parameters:msg (MessageThread) – The message to send.
Return type:concurrent.futures.Future
send(msg)[source]

Send a message. This method is await-able.

Returns a Future which you can await. The result will contain the message that has been sent.

In synchronous-mode the future finishes once the remote has released the message. In asynchronous-mode the future finishes once the message has been passed to the operating-system.

Awaiting can raise the exceptions: ConnectionError, TimeoutError, RuntimeError, ValueError, MemoryError. The exception contains the last error message if any generated by chirp. Also Exception for unknown errors. See Exceptions.

See also Concurrency.

May only be used from asyncio-event-loop-thread.

Parameters:msg (libchirp.asyncio.Message) – The message to send.
Return type:asyncio.Future
stop()

Stop the chirp-instance.

Message

class libchirp.asyncio.Message(cmsg=None)[source]

Bases: libchirp.MessageThread

Chirp message. To answer to message just replace the data and send it.

Note

The underlaying C type is annotated in parens. The properties of the message use asserts to check if the value has the correct type, length, range. You can disable these with python -O.

address

Get address.

If the message was received: The address of the remote the message was received from.

If the message will be sent: The address to send the message to.

This allows to reply to messages just by replacing data().

Returns:String representation generated by py:class:ipaddress.ip_address.
Return type:string
data

Get the data of the message.

Return type:bytes
has_slot

Return if the message has a slot.

If libchirp.Config.AUTO_RELEASE is False, you have to call release_slot()

Return type:bool
header

Get the header used by upper-layer protocols.

Users should not use it, except if you know what you are doing.

Return type:bytes
identity

Get identify the message and answers to it. (uint8_t[16]).

The identity can be used to find answers to a message, since replying to the message won’t change the identity.

If you need to uniquely identify the message, use the identity/serial pair, since the serial will change when replying to messages. (read-only)

Return type:bytes
port

Get port. (uint16_t).

If the message was received: The port of the remote the message was received from.

If the message will be sent: The port to send the message to.

This allows to reply to messages just by replacing data().

Return type:int
release()

Release the internal message-slot. This method is await-able.

Will also acknowledge the message if the remote requested a acknowledge-message.

The result of the future will be set to (identity, serial) once the message is released. If the message had no slot, the result will be set to None.

May only be used from asyncio-event-loop-thread.

Return type:asyncio.Future
release_slot()[source]

Release the internal message-slot. This method is await-able.

Will also acknowledge the message if the remote requested a acknowledge-message.

The result of the future will be set to (identity, serial) once the message is released. If the message had no slot, the result will be set to None.

May only be used from asyncio-event-loop-thread.

Return type:asyncio.Future
remote_identity

Detect the remote instance. (uint8_t[16]).

By default a node’s identity will change on each start of chirp. If multiple peers share state, a change in the remote_identity should trigger a reset of the state. Simply use the remote_identity as key in a dictionary of shared state. (read-only)

Return type:bytes
serial

Get the serial number of the message. (uint32_t).

Increases monotonic. Be aware of overflows, if want to use it for ordering use the delta: serialA - serialB. (read-only)

Return type:int