threadsafe_multimap.h

Go to the documentation of this file.

/*
 * threadsafe_multimap.h
 * 
 * Copyright (C) 2010  Thomas A. Vaughan
 * All rights reserved.
 *
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the <organization> nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THOMAS A. VAUGHAN ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THOMAS A. VAUGHAN BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 *
 * Basic threadsafe multimap (wrapper around std::multimap)
 */

#ifndef WAVEPACKET_THREADSAFE_MULTIMAP_H__
#define WAVEPACKET_THREADSAFE_MULTIMAP_H__

// includes --------------------------------------------------------------------
#include "common/common.h"
#include "smart_mutex.h"


////////////////////////////////////////////////////////////////////////////////
///
///     \ingroup threadsafe
///
///     A very simple map object that is safe for multiple threads to use at the
///     same time.  There is a single mutex protecting the entire map.
///
///     You can iterate using getIterator()/getNextElement().  However, that is
///     not guaranteed iteration.  Your iterator will be invalidated (and
///     getNextElement() will return false) if another thread has since updated
///     the map.
///
////////////////////////////////////////////////////////////////////////////////
template <class K, class T>
class threadsafe_multimap : protected std::multimap<K,T> {
private:
        // private typedefs ----------------------------------------------------
        typedef std::multimap<K,T>                      base_map_t;
        typedef typename std::multimap<K,T>::iterator   base_iterator_t;
        typedef typename std::pair<base_iterator_t, base_iterator_t> iter_pair_t;

public:
        // public typedefs -----------------------------------------------------
        class iterator_t {
        public:
                friend class threadsafe_multimap<K, T>;
        private:
                base_iterator_t         iter; // start at this element
                base_iterator_t         end;  // end before reaching here
                dword_t                 rvn;
        };

        // threadsafe_map class interface methods ------------------------------

        /// how many elements in the map
        int size(void) {
                        // not a const operation because we touch the mutex
                        mlock l(m_mutex);
                        return base_map_t::size();
                }

        /// how many elements with the given key
        int count(IN const K& key) {
                        mlock l(m_mutex);
                        return base_map_t::count(key);
                }

        /// insert the given object at the given key value
        void insert(IN const K& key, IN const T& t) {
                        mlock l(m_mutex);
                        ++m_rvn;
                        base_map_t::insert(std::pair<K, T>(key, t));
                }

        /// remove (erase) all elements with this key
        void remove(IN const K& key) {
                        mlock l(m_mutex);
                        ++m_rvn;
                        iter_pair_t pair = this->equal_range(key);
                        base_map_t::erase(pair.first, pair.second);
                }

        /// clear out (erase) the entire map
        void clear(void) {
                        mlock l(m_mutex);
                        ++m_rvn;
                        base_map_t::clear();
                }

        /// get an iterator (points to the first element in the map)
        void getIterator(OUT iterator_t& i) {
                        mlock l(m_mutex);
                        i.rvn = m_rvn;
                        i.iter = this->begin();
                        i.end = this->end();
                }

        /// get an iterator just for a particular key
        void getIterator(IN const K& key, OUT iterator_t& i) {
                        mlock l(m_mutex);
                        i.rvn = m_rvn;
                        iter_pair_t pair = base_map_t::equal_range(key);
                        i.iter = pair.first;
                        i.end = pair.second;
                }

        /// get next element in map and increment iterator
        bool getNextElement(IO iterator_t& i, OUT K& k, OUT T& t) {
                        mlock l(m_mutex);
                        T * pt = this->getNextElementInternal(i, k);
                        if (!pt)
                                return false;
                        t = *pt;
                        return true;
                }

        /// get next element without getting a local copy.  Caller had
        ///     better be sure that the element won't be removed after
        ///     this call!
        T * getNextElementUnsafe(IO iterator_t& i, OUT K& k) {
                        mlock l(m_mutex);
                        return this->getNextElementInternal(i, k);
                }

private:
        // private helper methods ----------------------------------------------
        T * getNextElementInternal(IN iterator_t& i, OUT K& k) {
                        // only used by other class methods!
                        // caller should already have mutex
                        if (i.rvn != this->m_rvn)
                                return NULL;    // iterator is now invalid!
                        if (i.end == i.iter)
                                return NULL;    // end of iteration

                        // iterator is good!
                        k = i.iter->first;
                        T * t = &i.iter->second;
                        ++i.iter;
                        return t;
                }

        // private member data -------------------------------------------------
        smart_mutex             m_mutex;
        dword_t                 m_rvn;
};


#endif  // WAVEPACKET_THREADSAFE_MULTIMAP_H__