Channels
This is the Dragon channels interface for Python
Classes
- class Message
Class for manipulating Dragon Channel Messages
Dragon Messages are the interface for providing or receiving Managed Memory buffers through Channels. This class provides methods for managing life cycle and direct access to memoryviews from Messages.
- bytes_memview()
Get a memoryview into the underlying message payload
- Returns
Memoryview object to underlying message payload
- static create_alloc(mpool, nbytes, hints=0, clientid=0, timeout=None)
Allocate memory and a new message object for inserting data into and sending
- Parameters
mpool – The MemoryPool to allocate from
nbytes – Size in bytes of the payload allocation
- Returns
New Message object
- static create_empty()
Create a new Message object with no memory backing
- Returns
New Message Object
- static create_from_mem(mem, hints=0, clientid=0)
Create a new Message object with no memory backing
- Returns
New Message Object
- destroy(free_mem=True)
Destroy the underlying message object in the channel, optionally freeing underlying memory
- Parameters
free_mem – Default True. Determines whether to free the allocated memory.
- Raises
ChannelError if message could not be freed.
- tobytes()
- Returns
Bytes object of the message payload
- class ChannelSendH
Sending handle for outgoing channel messages
- __init__(*args, **kwargs)
- send(msg: Message, dest_msg: Optional[Message] = None, ownership=0, blocking=True, timeout='USE_CHANNEL_SENDH_DEFAULT') None
Send a message through the channel. The default behavior is to use the blocking and timeout behavior from the send channel handle. Otherwise, the two parameters can be set as follows.
blocking == True and timeout == None means to block forever blocking == True and timeout > 0 means to block for timeout seconds blocking == True and timeout == 0 is a non-blocking send blocking == False is a non-blocking send no matter what timeout is Raises an exception if timeout < 0 no matter what blocking is.
- class ChannelRecvH
Receiving handle for incoming channel messages
- __init__(*args, **kwargs)
- recv(dest_msg: Optional[Message] = None, blocking=True, timeout='USE_CHANNEL_RECVH_DEFAULT')
Receive a message from the channel. The default behavior is to use the blocking and timeout behavior from the receive channel handle. Otherwise, the two parameters can be set as follows.
blocking == True and timeout == None means to block forever blocking == True and timeout > 0 means to block for timeout seconds blocking == True and timeout == 0 is a non-blocking receive blocking == False is a non-blocking receive no matter what timeout is Raises an exception if timeout < 0 no matter what blocking is.
- class Channel
Cython wrapper for channels
- __init__()
Create a new Channel object, tied to the provided MemoryPool. The c_uid specifies a unique identifier name to share with other processes. For another process to use the channel, it needs to be given a serialized instance of this channel or it can inherit access to it through the current process using this object.
- Parameters
mem_pool – Dragon MemoryPool object the channel should use for allocating its resources.
c_uid – A unique identifier for the channel
block_size – The size of each message block. None indicates to use the default. A channel that is to be used to share small messages may see some performance improvement by choosing a corresponding small block size. Messages may be bigger than the given block size. If messages are bigger they are stored separately from the channel but still use a message block when in the channel.
capacity – The number of messages the channel can hold. Optional, defaults to None.
lock_type – The type of lock to be used in locking the channel. Optional, defaults to None
fc_type – Unimplemented. Optional, defaults to None.
flags – ChannelFlags to use. Optional, defaults to None.
- Returns
A new Channel object using c_uid as its channel identifier.
- classmethod attach(serialized_bytes, mem_pool=None)
Attach to an existing channel through a serialized channel descriptor. When attaching a non-local channel the memory pool for the channel will also be non-local. Since the send_bytes method of Channel needs to make memory allocations, a user may choose to supply their own memory pool when attaching a non-local channel. Nothing prevents you from doing this with a local channel either. If no memory pool is provided and the channel being attached is non-local, then the default memory pool on this node will be used instead.
- Parameters
serialized_bytes – Bytes-like object containing a serialized channel descriptor to attach to.
mem_pool – A memory pool to use for allocations on the attached channel, primarily for send_bytes.
- Returns
New channel object attached to existing channel.
- Raises
ChannelError if channel could not be attached.
- destroy()
Destroys the channel.
- detach(serialize=False)
Detach from a channel and its underlying memory. Optionally also detach from the underlying pool.
- get_pool()
Retrieve the pool this Channel belongs to
- Returns
MemoryPool object
- classmethod make_process_local(timeout=None)
Create a process local channel which is a channel that exists for the sole purpose of use by the current process. The channel is unique to all nodes and may be shared with other processes but is managed with the life-cycle of the current process. When the current process, the one calling this function, exits, the process local channel it created via this call will also be destroyed.
This is especially useful for processes that need a channel to receive requests or need to have a place where responses to requests of other processes can be sent. Most likely calls to this function will exist inside of some other API.
- Parameters
timeout – Default is None which means to block without timeout until the channel is made. This should not timeout and should be processed quickly. If a timeout value is specified, it is the number of seconds to wait which may be a float.
- Returns
A new channel object.
- Raises
ChannelError if there was an error. Note that the Dragon run-time must be running to use this function as it interacts with Local Services on the node on which it is called.
- poll(timeout=None, wait_mode=2, event_mask=1, poll_result=None)
Poll on a channel. If a PollResult is provided, the result and return code are provided via the PollResult. Otherwise it will raise an exception on an error condition.
- Parameters
timeout (float) – Timeout for the poll operation in seconds. Defaults to None..
wait_mode (dtypes.WaitMode) – How to poll on the channel, defaults to IDLE_WAIT.
event_mask (EventType) – Which event on the channel to poll on, defaults to POLLIN.
poll_result – If there is a value returned by poll, it is set in this reference variable. If a
PollResult value is provided, then poll will not raise an exception. It will instead return the result and the return code via this PollResult. :type poll_result: PollResult
- recvh(notification_type=RecvNotifType(1), signal=None, wait_mode=2, timeout=None)
Create a Receive Handle object and return it unopened.
- Returns
New ChannelRecvH object.
- sendh(return_mode=ReturnWhen(1), wait_mode=2, timeout=None)
Create a Send Handle object and return it unopened.
- Returns
New ChannelSendH object.
- serialize()
Serialize a channel descriptor for use in storage or communication. Calling this will, if not already serialized, store the serialized data in self._serial. Subsequent calls will return a copy of that data as a python bytes object. This allows for holding onto the serialized data during detach for later use.
- Returns
Memoryview of the serialized channel descriptor.
- class Peer2PeerReadingChannelFile
File-like interface for reading any size message efficiently from a Channel.
This is the dual end to the Peer2PeerWritingChannelFile class above.
This interface is NOT thread safe. If multiple threads will drive this, each thread must have its own object.
- __init__()
This object sits read calls on top of a channel object.
- Parameters
channel – a Channel object
options – an options object, tbd. Strategy on taking blocks from the pool, etc.
- class Many2ManyReadingChannelFile
Following similar approach with Peer2PeerReadingChannelFile. This is used when there are multiple readers.
- __init__(*args, **kwargs)
- get_remaining_data()
Allocate memory for storing the dict message with (key, value) information. This is used to extract the offset, where value is stored in the message. Currently this is used for the use case info of the dragon dict.
- Returns
A tuple with new memory alloc object and start offset of the value
- class Many2ManyWritingChannelFile
Following similar approach as Peer2PeerWritingChannelFile, with the main difference that this includes a many to many scheme of communication. This means, we have to write a single message in the channel coming from each writer.
- __init__(*args, **kwargs)
- class GatewayMessage
Cython wrapper for Dragon Channel Gateway Messages
- destroy()
Destroy the underlying message object for send operations
- get_dest_mem_descr_ser
- Returns
Memoryview of the destination serialized memory descriptor for gets
- send_dest_mem_descr_ser
- Returns
Memoryview of the destination serialized memory descriptor for sends
- target_ch_ser
- Returns
Memoryview of the serialized target channel descriptor
Functions
- register_gateways_from_env()
TBD
- discard_gateways()
TBD
Enums
- class OwnershipOnSend
An enumeration.
- class LockType
An enumeration.
- class EventType
An enumeration.
- class FlowControl
An enumeration.
- class ChannelFlags
An enumeration.
Exceptions
- exception ChannelTimeout
- exception ChannelHandleNotOpenError
- exception ChannelSendError
- exception ChannelSendTimeout
- exception ChannelFull
- exception ChannelRecvError
- exception ChannelRecvTimeout
- exception ChannelEmpty
- exception ChannelBarrierBroken
- exception ChannelBarrierReady
- exception ChannelRemoteOperationNotSupported