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

Bases: Exception

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

get_refcnt(identifier)
release_refcnt(identifier)