Queue

exception Empty

Bases: Exception

exception Full

Bases: Exception

class Queue(service_name, name, context)

Bases: hazelcast.proxy.base.PartitionSpecificProxy

Concurrent, blocking, distributed, observable queue.

Queue is not a partitioned data-structure. All of the Queue content is stored in a single machine (and in the backup). Queue will not scale by adding more members in the cluster.

add(item)

Adds the specified item to this queue if there is available space.

Parameters

item – The specified item.

Returns

True if element is successfully added, False otherwise.

Return type

hazelcast.future.Future[bool]

add_all(items)

Adds the elements in the specified collection to this queue.

Parameters

items (list) – Collection which includes the items to be added.

Returns

True if this queue is changed after call, False otherwise.

Return type

hazelcast.future.Future[bool]

add_listener(include_value=False, item_added_func=None, item_removed_func=None)

Adds an item listener for this queue. Listener will be notified for all queue add/remove events.

Parameters

• include_value (bool) – Whether received events include the updated item or not.

• item_added_func (function) – Function to be called when an item is added to this set.

• item_removed_func (function) – Function to be called when an item is deleted from this set.

Returns

A registration id which is used as a key to remove the listener.

Return type

hazelcast.future.Future[str]

clear()

Clears this queue. Queue will be empty after this call.

Returns

Return type

hazelcast.future.Future[None]

contains(item)

Determines whether this queue contains the specified item or not.

Parameters

item – The specified item to be searched.

Returns

True if the specified item exists in this queue, False otherwise.

Return type

hazelcast.future.Future[bool]

contains_all(items)

Determines whether this queue contains all of the items in the specified collection or not.

Parameters

items (list) – The specified collection which includes the items to be searched.

Returns

True if all of the items in the specified collection exist

in this queue, False otherwise.

Return type

hazelcast.future.Future[bool]

drain_to(target_list, max_size=- 1)

Transfers all available items to the given target_list and removes these items from this queue.

If a max_size is specified, it transfers at most the given number of items. In case of a failure, an item can exist in both collections or none of them.

This operation may be more efficient than polling elements repeatedly and putting into collection.

Parameters

• target_list (list) – the list where the items in this queue will be transferred.

• max_size (int) – The maximum number items to transfer.

Returns

Number of transferred items.

Return type

hazelcast.future.Future[int]

iterator()

Returns all of the items in this queue.

Returns

Collection of items in this queue.

Return type

list

is_empty()

Determines whether this set is empty or not.

Returns

True if this queue is empty, False otherwise.

Return type

hazelcast.future.Future[bool]

offer(item, timeout=0)

Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.

If there is no space currently available:

• If a timeout is provided, it waits until this timeout elapses and returns the result.

• If a timeout is not provided, returns False immediately.

Parameters

• item – The item to be added.

• timeout (int) – Maximum time in seconds to wait for addition.

Returns

True if the element was added to this queue, False otherwise.

Return type

hazelcast.future.Future[bool]

peek()

Retrieves the head of queue without removing it from the queue.

Returns

the head of this queue, or None if this queue is empty.

Return type

hazelcast.future.Future[any]

poll(timeout=0)

Retrieves and removes the head of this queue.

If this queue is empty:

• If a timeout is provided, it waits until this timeout elapses and returns the result.

• If a timeout is not provided, returns None.

Parameters

timeout (int) – Maximum time in seconds to wait for addition.

Returns

The head of this queue, or None if this queue is empty

or specified timeout elapses before an item is added to the queue.

Return type

hazelcast.future.Future[any]

put(item)

Adds the specified element into this queue.

If there is no space, it waits until necessary space becomes available.

Parameters

item – The specified item.

Returns

Return type

hazelcast.future.Future[None]

remaining_capacity()

Returns the remaining capacity of this queue.

Returns

Remaining capacity of this queue.

Return type

hazelcast.future.Future[int]

remove(item)

Removes the specified element from the queue if it exists.

Parameters

item – The specified element to be removed.

Returns

True if the specified element exists in this queue, False otherwise.

Return type

hazelcast.future.Future[bool]

remove_all(items)

Removes all of the elements of the specified collection from this queue.

Parameters

items (list) – The specified collection.

Returns

True if the call changed this queue, False otherwise.

Return type

hazelcast.future.Future[bool]

remove_listener(registration_id)

Removes the specified item listener.

Returns silently if the specified listener was not added before.

Parameters

registration_id (str) – Id of the listener to be deleted.

Returns

True if the item listener is removed, False otherwise.

Return type

hazelcast.future.Future[bool]

retain_all(items)

Removes the items which are not contained in the specified collection.

In other words, only the items that are contained in the specified collection will be retained.

Parameters

items (list) – Collection which includes the elements to be retained in this set.

Returns

True if this queue changed as a result of the call, False otherwise.

Return type

hazelcast.future.Future[bool]

size()

Returns the number of elements in this collection.

If the size is greater than 2**31 - 1, it returns 2**31 - 1

Returns

Size of the queue.

Return type

hazelcast.future.Future[int]

take()

Retrieves and removes the head of this queue, if necessary, waits until an item becomes available.

Returns

The head of this queue.

Return type

hazelcast.future.Future[any]