From 31f9379a537f13504c866c7551e7f8c01a523c67 Mon Sep 17 00:00:00 2001 From: Derek Murray Date: Wed, 8 Jun 2016 09:10:40 -0800 Subject: Improves the `tf.QueueBase` documentation with regard to error conditions. Fixes #2326. Change: 124364329 --- tensorflow/python/ops/data_flow_ops.py | 60 +++++++++++++++++++++++++++------- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/tensorflow/python/ops/data_flow_ops.py b/tensorflow/python/ops/data_flow_ops.py index 9c6feb4ed7..5f53b3dbc5 100644 --- a/tensorflow/python/ops/data_flow_ops.py +++ b/tensorflow/python/ops/data_flow_ops.py @@ -276,6 +276,15 @@ class QueueBase(object): If the queue is full when this operation executes, it will block until the element has been enqueued. + At runtime, this operation may raise an error if the queue is + [closed](#QueueBase.close) before or during its execution. If the + queue is closed before this operation runs, + `tf.errors.AbortedError` will be raised. If this operation is + blocked, and either (i) the queue is closed by a close operation + with `cancel_pending_enqueues=True`, or (ii) the session is + [closed](../../api_docs/python/client.md#Session.close), + `tf.errors.CancelledError` will be raised. + Args: vals: A tensor, a list or tuple of tensors, or a dictionary containing the values to enqueue. @@ -305,6 +314,15 @@ class QueueBase(object): If the queue is full when this operation executes, it will block until all of the elements have been enqueued. + At runtime, this operation may raise an error if the queue is + [closed](#QueueBase.close) before or during its execution. If the + queue is closed before this operation runs, + `tf.errors.AbortedError` will be raised. If this operation is + blocked, and either (i) the queue is closed by a close operation + with `cancel_pending_enqueues=True`, or (ii) the session is + [closed](../../api_docs/python/client.md#Session.close), + `tf.errors.CancelledError` will be raised. + Args: vals: A tensor, a list or tuple of tensors, or a dictionary from which the queue elements are taken. @@ -357,6 +375,14 @@ class QueueBase(object): If the queue is empty when this operation executes, it will block until there is an element to dequeue. + At runtime, this operation may raise an error if the queue is + [closed](#QueueBase.close) before or during its execution. If the + queue is closed, the queue is empty, and there are no pending + enqueue operations that can fulfil this request, + `tf.errors.OutOfRangeError` will be raised. If the session is + [closed](../../api_docs/python/client.md#Session.close), + `tf.errors.CancelledError` will be raised. + Args: name: A name for the operation (optional). @@ -386,6 +412,14 @@ class QueueBase(object): If the queue is closed and there are less than `n` elements left, then an `OutOfRange` exception is raised. + At runtime, this operation may raise an error if the queue is + [closed](#QueueBase.close) before or during its execution. If the + queue is closed, the queue contains fewer than `n` elements, and + there are no pending enqueue operations that can fulfil this + request, `tf.errors.OutOfRangeError` will be raised. If the + session is [closed](../../api_docs/python/client.md#Session.close), + `tf.errors.CancelledError` will be raised. + Args: n: A scalar `Tensor` containing the number of elements to dequeue. name: A name for the operation (optional). @@ -412,18 +446,20 @@ class QueueBase(object): """Dequeues and concatenates `n` elements from this queue. **Note** This operation is not supported by all queues. If a queue does not - support DequeueUpTo, then an Unimplemented exception is raised. - - This operation concatenates queue-element component tensors along the - 0th dimension to make a single component tensor. All of the components - in the dequeued tuple will have size `n` in the 0th dimension. - - If the queue is closed and there are more than `0` but less than `n` - elements remaining, then instead of raising an `OutOfRange` exception like - `dequeue_many`, the remaining elements are returned immediately. - If the queue is closed and there are `0` elements left in the queue, then - an `OutOfRange` exception is raised just like in `dequeue_many`. - Otherwise the behavior is identical to `dequeue_many`: + support DequeueUpTo, then a `tf.errors.UnimplementedError` is raised. + + This operation concatenates queue-element component tensors along + the 0th dimension to make a single component tensor. If the queue + has not been closed, all of the components in the dequeued tuple + will have size `n` in the 0th dimension. + + If the queue is closed and there are more than `0` but fewer than + `n` elements remaining, then instead of raising a + `tf.errors.OutOfRangeError` like [`dequeue_many`](#QueueBase.dequeue_many), + the remaining elements are returned immediately. If the queue is + closed and there are `0` elements left in the queue, then a + `tf.errors.OutOfRangeError` is raised just like in `dequeue_many`. + Otherwise the behavior is identical to `dequeue_many`. Args: n: A scalar `Tensor` containing the number of elements to dequeue. -- cgit v1.2.3