def _claimed(self, queue_name, claim_id,
                 expires=None, limit=None, project=None):

        if claim_id is None:
            claim_id = {'$ne': None}

        query = {
            PROJ_QUEUE: utils.scope_queue_name(queue_name, project),
            'c.id': claim_id,
            'c.e': {'$gt': expires or timeutils.utcnow_ts()},
        }

        # NOTE(kgriffs): Claimed messages bust be queried from
        # the primary to avoid a race condition caused by the
        # multi-phased "create claim" algorithm.
        preference = pymongo.read_preferences.ReadPreference.PRIMARY
        collection = self._collection(queue_name, project)
        msgs = collection.find(query, sort=[('k', 1)],
                               read_preference=preference).hint(
                                   CLAIMED_INDEX_FIELDS
                               )

        if limit is not None:
            msgs = msgs.limit(limit)

        now = timeutils.utcnow_ts()

        def denormalizer(msg):
            doc = _basic_message(msg, now)
            doc['claim'] = msg['c']

            return doc

        return utils.HookedCursor(msgs, denormalizer)

    def count(self, queue_name, project=None, include_claimed=False):
        """Return total number of messages in a queue.

        This method is designed to very quickly count the number
        of messages in a given queue. Expired messages are not
        counted, of course. If the queue does not exist, the
        count will always be 0.

        Note: Some expired messages may be included in the count if
            they haven't been GC'd yet. This is done for performance.
        """
        query = {
            # Messages must belong to this queue
            'p': project,
            'q': queue_name,

            # The messages can not be expired
            'e': {'$gt': timeutils.utcnow_ts()},
        }

        if not include_claimed:
            # Exclude messages that are claimed
            query['c.e'] = {'$lte': timeutils.utcnow_ts()}

        return self._col.find(query).hint(COUNTING_INDEX_FIELDS).count()

    def bulk_get(self, queue, message_ids, project):
        if project is None:
            project = ''

        message_ids = [id for id in
                       map(utils.msgid_decode, message_ids)
                       if id is not None]

        statement = sa.sql.select([tables.Messages.c.id,
                                   tables.Messages.c.body,
                                   tables.Messages.c.ttl,
                                   tables.Messages.c.created])

        and_stmt = [tables.Messages.c.id.in_(message_ids),
                    tables.Queues.c.name == queue,
                    tables.Queues.c.project == project,
                    tables.Messages.c.ttl >
                    sfunc.now() - tables.Messages.c.created]

        j = sa.join(tables.Messages, tables.Queues,
                    tables.Messages.c.qid == tables.Queues.c.id)

        statement = statement.select_from(j).where(sa.and_(*and_stmt))

        now = timeutils.utcnow_ts()
        records = self.driver.run(statement)
        for id, body, ttl, created in records:
            yield {
                'id': utils.msgid_encode(id),
                'ttl': ttl,
                'age': now - calendar.timegm(created.timetuple()),
                'body': json.loads(body),
            }

    def _count(self, queue_name, project=None, include_claimed=False):
        """Return total number of messages in a queue.

        This method is designed to very quickly count the number
        of messages in a given queue. Expired messages are not
        counted, of course. If the queue does not exist, the
        count will always be 0.

        Note: Some expired messages may be included in the count if
            they haven't been GC'd yet. This is done for performance.
        """
        query = {
            # Messages must belong to this queue and project.
            PROJ_QUEUE: utils.scope_queue_name(queue_name, project),

            # NOTE(kgriffs): Messages must be finalized (i.e., must not
            # be part of an unfinalized transaction).
            #
            # See also the note wrt 'tx' within the definition
            # of ACTIVE_INDEX_FIELDS.
            'tx': None,
        }

        if not include_claimed:
            # Exclude messages that are claimed
            query['c.e'] = {'$lte': timeutils.utcnow_ts()}

        collection = self._collection(queue_name, project)
        return collection.find(query).hint(COUNTING_INDEX_FIELDS).count()

    def list(self, queue_name, project=None, marker=None, limit=None,
             echo=False, client_uuid=None, include_claimed=False):

        if limit is None:
            limit = CFG.default_message_paging

        if marker is not None:
            try:
                marker = int(marker)
            except ValueError:
                yield iter([])

        messages = self._list(queue_name, project=project, marker=marker,
                              client_uuid=client_uuid,  echo=echo,
                              include_claimed=include_claimed, limit=limit)

        marker_id = {}

        now = timeutils.utcnow_ts()

        def denormalizer(msg):
            marker_id['next'] = msg['k']

            return _basic_message(msg, now)

        yield utils.HookedCursor(messages, denormalizer)
        yield str(marker_id['next'])

    def stats(self, name, project=None):
        if not self.exists(name, project=project):
            raise errors.QueueDoesNotExist(name, project)

        q_id = utils.scope_queue_name(name, project)
        q_info = self._client.hgetall(q_id)

        claimed = int(q_info['cl'])
        total = int(q_info['c'])
        msg_ctrl = self.driver.message_controller
        now = timeutils.utcnow_ts()

        message_stats = {
            'claimed': claimed,
            'free': total-claimed,
            'total': total
        }

        try:
            newest = msg_ctrl.first(name, project, 1)
            oldest = msg_ctrl.first(name, project, -1)
        except errors.QueueIsEmpty:
            pass
        else:
            message_stats['newest'] = utils.stat_message(newest, now)
            message_stats['oldest'] = utils.stat_message(oldest, now)

        return {'messages': message_stats}

 def _exists_unlocked(self, key):
     now = timeutils.utcnow_ts()
     try:
         timeout = self._cache[key][0]
         return not timeout or now <= timeout
     except KeyError:
         return False

    def get(self, queue_name, message_id, project=None):
        """Gets a single message by ID.

        :raises: exceptions.MessageDoesNotExist
        """
        mid = utils.to_oid(message_id)
        if mid is None:
            raise exceptions.MessageDoesNotExist(message_id, queue_name,
                                                 project)

        now = timeutils.utcnow_ts()

        query = {
            '_id': mid,
            'p': project,
            'q': queue_name,
            'e': {'$gt': now}
        }

        message = list(self._col.find(query).limit(1).hint(ID_INDEX_FIELDS))

        if not message:
            raise exceptions.MessageDoesNotExist(message_id, queue_name,
                                                 project)

        return _basic_message(message[0], now)

    def _get_unlocked(self, key, default=None):
        now = timeutils.utcnow_ts()

        try:
            timeout, value = self._cache[key]
        except KeyError:
            return (0, default)

        if timeout and now >= timeout:

            # NOTE(flaper87): Record expired,
            # remove it from the cache but catch
            # KeyError and ValueError in case
            # _purge_expired removed this key already.
            try:
                del self._cache[key]
            except KeyError:
                pass

            try:
                # NOTE(flaper87): Keys with ttl == 0
                # don't exist in the _keys_expires dict
                self._keys_expires[timeout].remove(key)
            except (KeyError, ValueError):
                pass

            return (0, default)

        return (timeout, value)

    def stats(self, name, project=None):
        if not self.exists(name, project=project):
            raise errors.QueueDoesNotExist(name, project)

        controller = self.driver.message_controller

        active = controller._count(name, project=project,
                                   include_claimed=False)
        total = controller._count(name, project=project,
                                  include_claimed=True)

        message_stats = {
            'claimed': total - active,
            'free': active,
            'total': total,
        }

        try:
            oldest = controller.first(name, project=project, sort=1)
            newest = controller.first(name, project=project, sort=-1)
        except errors.QueueIsEmpty:
            pass
        else:
            now = timeutils.utcnow_ts()
            message_stats['oldest'] = utils.stat_message(oldest, now)
            message_stats['newest'] = utils.stat_message(newest, now)

        return {'messages': message_stats}

    def list(self, queue_name, project=None, marker=None,
             limit=storage.DEFAULT_MESSAGES_PER_PAGE,
             echo=False, client_uuid=None, include_claimed=False):

        if marker is not None:
            try:
                marker = int(marker)
            except ValueError:
                yield iter([])

        messages = self._list(queue_name, project=project, marker=marker,
                              client_uuid=client_uuid,  echo=echo,
                              include_claimed=include_claimed, limit=limit)

        marker_id = {}

        now = timeutils.utcnow_ts()

        # NOTE (kgriffs) @utils.raises_conn_error not needed on this
        # function, since utils.HookedCursor already has it.
        def denormalizer(msg):
            marker_id['next'] = msg['k']

            return _basic_message(msg, now)

        yield utils.HookedCursor(messages, denormalizer)
        yield str(marker_id['next'])

    def claimed(self, queue, claim_id=None, expires=None, limit=None):

        query = {
            "c.id": claim_id,
            "q": utils.to_oid(queue),
        }
        if not claim_id:
            # lookup over c.id to use the index
            query["c.id"] = {"$ne": None}
        if expires:
            query["c.e"] = {"$gt": expires}

        msgs = self._col.find(query, sort=[("_id", 1)])

        if limit:
            msgs = msgs.limit(limit)

        now = timeutils.utcnow_ts()

        def denormalizer(msg):
            oid = msg.get("_id")
            age = now - utils.oid_ts(oid)

            return {
                "id": str(oid),
                "age": age,
                "ttl": msg["t"],
                "body": msg["b"],
                "claim": msg["c"]
            }

        return utils.HookedCursor(msgs, denormalizer)

    def _remove_expired(self, queue_name, project):
        """Removes all expired messages except for the most recent
        in each queue.

        This method is used in lieu of mongo's TTL index since we
        must always leave at least one message in the queue for
        calculating the next marker.

        :param queue_name: name for the queue from which to remove
            expired messages
        :param project: Project queue_name belong's too
        """

        # Get the message with the highest marker, and leave
        # it in the queue
        head = self._col.find_one({'p': project, 'q': queue_name},
                                  sort=[('k', -1)], fields={'k': 1})

        if head is None:
            # Assume queue was just deleted via a parallel request
            LOG.debug(_(u'Queue %s is empty or missing.') % queue_name)
            return

        query = {
            'p': project,
            'q': queue_name,
            'k': {'$ne': head['k']},
            'e': {'$lte': timeutils.utcnow_ts()},
        }

        self._col.remove(query, w=0)

 def _set_claim_counter(self, q_id, count):
     q_info = {
         'c': self._get_queue_info(q_id, 'c'),
         'cl': count,
         'm': self._get_queue_info(q_id, 'm'),
         't': timeutils.utcnow_ts()
     }
     self._client.hmset(q_id, q_info)

    def _set_unlocked(self, key, value, ttl=0):
        expires_at = 0
        if ttl != 0:
            expires_at = timeutils.utcnow_ts() + ttl

        self._cache[key] = (expires_at, value)

        if expires_at:
            self._keys_expires[expires_at].add(key)

    def first(self, queue_name, project=None, sort=1):
        cursor = self._list(queue_name, project=project, include_claimed=True, sort=sort, limit=1)
        try:
            message = next(cursor)
        except StopIteration:
            raise errors.QueueIsEmpty(queue_name, project)

        now = timeutils.utcnow_ts()
        return _basic_message(message, now)

 def get(self, queue, message_id, project):
     body, ttl, created = self._get(queue, message_id, project)
     now = timeutils.utcnow_ts()
     return {
         'id': message_id,
         'ttl': ttl,
         'age': now - calendar.timegm(created.timetuple()),
         'body': json.loads(body),
     }

 def it():
     now = timeutils.utcnow_ts()
     for id, body, ttl, created in records:
         marker_id['next'] = id
         yield {
             'id': utils.msgid_encode(id),
             'ttl': ttl,
             'age': now - calendar.timegm(created.timetuple()),
             'body': json.loads(body),
         }

    def _incr_append(self, key, other):
        with lockutils.lock(key):
            timeout, value = self._get_unlocked(key)

            if value is None:
                return None

            ttl = timeutils.utcnow_ts() - timeout
            new_value = value + other
            self._set_unlocked(key, new_value, ttl)
            return new_value

    def _inc_counter(self, name, project=None, amount=1, window=None):
        """Increments the message counter and returns the new value.

        :param name: Name of the queue to which the counter is scoped
        :param project: Queue's project name
        :param amount: (Default 1) Amount by which to increment the counter
        :param window: (Default None) A time window, in seconds, that
            must have elapsed since the counter was last updated, in
            order to increment the counter.

        :returns: Updated message counter value, or None if window
            was specified, and the counter has already been updated
            within the specified time period.

        :raises: storage.errors.QueueDoesNotExist
        """
        now = timeutils.utcnow_ts()

        update = {'$inc': {'c.v': amount}, '$set': {'c.t': now}}
        query = _get_scoped_query(name, project)
        if window is not None:
            threshold = now - window
            query['c.t'] = {'$lt': threshold}

        while True:
            try:
                doc = self._collection.find_and_modify(
                    query, update, new=True, fields={'c.v': 1, '_id': 0})

                break
            except pymongo.errors.AutoReconnect as ex:
                LOG.exception(ex)

        if doc is None:
            if window is None:
                # NOTE(kgriffs): Since we did not filter by a time window,
                # the queue should have been found and updated. Perhaps
                # the queue has been deleted?
                message = _(u'Failed to increment the message '
                            u'counter for queue %(name)s and '
                            u'project %(project)s')
                message %= dict(name=name, project=project)

                LOG.warning(message)

                raise errors.QueueDoesNotExist(name, project)

            # NOTE(kgriffs): Assume the queue existed, but the counter
            # was recently updated, causing the range query on 'c.t' to
            # exclude the record.
            return None

        return doc['c']['v']