threadsafe_map.h

Go to the documentation of this file.

/*
 * threadsafe_map.h
 * 
 * Copyright (C) 2007,2009  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 map (wrapper around std::map)
 */

#ifndef WAVEPACKET_THREADSAFE_MAP_H__
#define WAVEPACKET_THREADSAFE_MAP_H__

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


////////////////////////////////////////////////////////////////////////////////
///
///     threadsafe map object
///
///     \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_map : protected std::map<K,T> {
private:
        // private typedefs ----------------------------------------------------
        typedef std::map<K,T>                           base_map_t;
        typedef typename std::map<K,T>::iterator        base_iterator_t;
        typedef threadsafe_map<K, T>                    map_t;

public:
        // public typedefs -----------------------------------------------------
        struct iterator_t {
        public:
                friend class threadsafe_map<K, T>;
        private:
                base_iterator_t         iter;
                dword_t                 rvn;
        };

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

        /// how many elements in the map
        int size(void) const throw() {
                        map_t * pThis = this->getNonConst();
                        mlock l(pThis->m_mutex);
                        return base_map_t::size();
                }

        /// insert the given object at the given key value (map, not multimap!)
        void insert(IN const K& key, IN const T& t) {
                        mlock l(m_mutex);
                        ++m_rvn;
                        this->operator[](key) = t;
                }

        /// retrieve value at key--true if there is a value there
        bool lookup(IN const K& key, OUT T& t) const throw() {
                        map_t * pThis = this->getNonConst();
                        mlock l(pThis->m_mutex);
                        base_iterator_t i = pThis->find(key);
                        if (pThis->end() != i) {
                                t = i->second;  // note: caller gets a copy!
                                return true;
                        }
                        return false;   // not found!
                }

        /// remove (erase) the element at key, if there is one
        bool remove(IN const K& key) {
                        mlock l(m_mutex);
                        base_iterator_t i = this->find(key);
                        if (this->end() != i) {
                                ++m_rvn;
                                this->erase(i);
                                return true;
                        }
                        return false;
                }

        /// 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) const throw() {
                        map_t * pThis = this->getNonConst();
                        mlock l(pThis->m_mutex);
                        i.rvn = m_rvn;
                        i.iter = pThis->begin();
                }

        /// get next element in map and increment iterator
        bool getNextElement(IO iterator_t& i, OUT K& k, OUT T& t) const {
                        map_t * pThis = this->getNonConst();
                        mlock l(pThis->m_mutex);
                        if (i.rvn != this->m_rvn)
                                return false;   // iterator is now invalid!
                        if (pThis->end() == i.iter)
                                return false;   // end of iteration

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

private:
        // private helper methods ----------------------------------------------
        // cast to avoid const-ness.  This is because read-only operations need
        //      to hold the mutex
        map_t * getNonConst(void) const throw() {
                        return (map_t *) this;
                }

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


#endif  // WAVEPACKET_THREADSAFE_MAP_H__