dragon.globalservices.channel

Global Services API for the Channels primary resource component.

Functions

create(m_uid[, user_name, options, soft, ...])

Asks Global Services to create a new channel

destroy(identifier, *[, just_decref])

Asks Global Services to destroy a specified channel.

get_list()

Asks Global Services for a list of the c_uids of all currently active channels

get_refcnt(identifier)

join(identifier[, timeout])

Waits for a channel with a particular name to get made.

query(identifier, *[, inc_refcnt])

Asks Global Services for the ChannelDescriptor by c_uid or name

release_refcnt(identifier)

wait(identifier[, state])

Wait for channel to be in a specified state.

wait_for(identifier, predicate[, timeout, ...])

Wait for predicate to return True.

Exceptions

ChannelError

exception ChannelError
create(m_uid, user_name='', options=None, soft=False, puid_override=None)

Asks Global Services to create a new channel

Parameters

  • m_uid – m_uid of pool to create the channel in

  • user_name – Requested user specified reference name

  • options – ChannelOptions object, what options to apply to creation

  • soft – Default False. If channel already exists with given name, do not create and return descriptor instead.

  • puid_override – Only needed when the channel is being created on behalf of some other process. Normally this is not needed.

Returns

ChannelDescriptor object

get_list()

Asks Global Services for a list of the c_uids of all currently active channels

TODO: add some options to this, and to the message itself, to have a finer control over which channels you get back. Deferring until we have a use case, but one that springs to mind is channels in a particular pool by m_uid.

Returns

list of the c_uids of all currently existing channels

query(identifier, *, inc_refcnt=False)

Asks Global Services for the ChannelDescriptor by c_uid or name

Note you can only query currently existing channels

Parameters

  • identifier – string indicating channel name or integer indicating a c_uid

  • inc_refcnt – bool indicating whether this query is also to inc the refcnt on the channel

Returns

ChannelDescriptor object corresponding to specified channel

Raises

ChannelError if there is no such channel

wait_for(identifier, predicate, timeout=None, tries=1, interval=0.1)

Wait for predicate to return True. predicate must be a callable that takes a ChannelDescriptor instance. A timeout may be provided giving the maximum time to wait after a minimum number of tries for predicate to return True are completed.

Parameters

  • identifier – String indicating channel name or integer indicating a c_uid

  • predicate – Callable that takes a ChannelDescriptor instance and returns a boolean

  • timeout – Number of seconds before timing out (default: infinite)

  • tries – Minimum number of query attempts before timing out (default: 1)

  • interval – Number of seconds to sleep in between query attempts (default: 0.1)

Returns

ChannelDescriptor object corresponding to the specified channel

Raises

TypeError if predicate is not callable

Raises

ChannelError if there is no such channel

Raises

TimeoutError if the number of tries is exhausted and the timeout expires

wait(identifier, state=State.DEAD, **kwds)

Wait for channel to be in a specified state. Other keyword arguments are passed through to wait_for().

Parameters

  • identifier – String indicating channel name or integer indicating a c_uid

  • state – Desired ChannelDescriptor.State (default: DEAD)

Returns

ChannelDescriptor object corresponding to the specified channel

Raises

ChannelError if there is no such channel

Raises

TimeoutError if the number of tries is exhausted and the timeout expires

join(identifier, timeout=None)

Waits for a channel with a particular name to get made.

Parameters

  • identifier – string indicating channel name

  • timeout – Time in seconds to timeout. if absent, block indefinitely.

Returns

ChannelDescriptor for the channel specified

Raises

TimeoutError if the timeout expires

destroy(identifier, *, just_decref=False)

Asks Global Services to destroy a specified channel.

Parameters

  • just_decref – bool default False, just decrement refcount, not hard destroy.

  • identifier – string indicating channel name or integer indicating a c_uid

Returns

Nothing if successful

Raises

ChannelError if there is no such channel