[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/vutil/listener.hh

Go to the documentation of this file.

/*
    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001-2003 Peter Amstutz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

    Peter Amstutz <http://www.interreality.org>
*/
#ifndef _VUTIL_LISTENER_HH_
#define _VUTIL_LISTENER_HH_

/** @file
    Defines ChildChangeListener, ParentChangeListener, and TypeChangeListener.
*/

#include <vos/vutil/vutildefs.hh>
#include <vos/vutil/refcount.hh>
#include <vos/vutil/taskqueue.hh>

#include <string>

namespace VUtil
{
    /** @class ListenerTask listener.hh vos/vos/listener.hh
        @ingroup libvutil

        Template class used to define the task of delivering a
        particular event object to a particular listener object.  An
        Event class supplied to this template must implement the
        following method, which makes the event deliver itself to the
        supplied Listener:

        @code
        void Event::deliverTo(Listener*);
        @endcode
    */
    template<class Listener, class Event> class ListenerTask : public Task
    {
    private:
        Listener* l;
        vRef<Event> e;

    public:
        /** Constructor.
            @param li the listener object to deliver the event to
            @param ev the event to be delivered
        */
        ListenerTask(Listener* li, Event* ev) : l(li), e(ev, true) {
            if(RefCounted* rc = dynamic_cast<RefCounted*>(l)) {
                rc->acquire();
            }
        }

        /** The actual task.  Because this is a generic template, we
            don't know ahead of time what method on the listener we
            actually want to call.  So we call the method deliverTo()
            on the event, and pass it the listener object; this has
            event deliver itself to the listener by calling the
            appropriate method on the listener.
         */
        virtual void doTask() {
            e->deliverTo(l);
        }

        /** Destructor */
        virtual ~ListenerTask() {
            if(RefCounted* rc = dynamic_cast<RefCounted*>(l)) {
                rc->release();
            }
        }
    };

    /** @class ListenerBase listener.hh vos/vos/listener.hh
        @ingroup libvutil

        Template base class for the listener pattern.  This manages a
        list of pointers to listeners to be notified when
        distributeEvent() is called.  This class is threadsafe.
    */
    template<class Listener, class Event> class ListenerBase : public ObjectExciseListener
    {
    private:
        boost::mutex listeners_mutex;
        std::set<Listener*> listeners;
        bool inClear;
        bool async;

    public:
        /** Constructor */
        ListenerBase() : async(true) { }

        /** Destructor.  Cleans up the listener list. */
        virtual ~ListenerBase() {
            clearListeners();
        }

        /** Add a listener.  Knows about RefCounted objects (they will
            be acquired and an excise listener added).

            @param l the listener object to add.
        */
        void addListener(Listener* l) {
            boost::mutex::scoped_lock lk(listeners_mutex);

            if(listeners.count(l) == 0) {
                if(RefCounted* rc = dynamic_cast<RefCounted*>(l)) {
                    rc->acquire();
                    rc->addExciseListener(this);
                }
                listeners.insert(l);
            }
        }

        /** Remove a listener.  Knows about RefCounted objects (they
            will be released and the excise listener removed).
            @param l the listener to remove.
         */
        void removeListener(Listener* l) {
            if(! inClear) {
                boost::mutex::scoped_lock lk(listeners_mutex);

                if(listeners.count(l) > 0) {
                    listeners.erase(l);
                    if(RefCounted* rc = dynamic_cast<RefCounted*>(l)) {
                        rc->removeExciseListener(this);
                        rc->release();
                    }
                }
            }
        }

        /** Remove all listeners.  Knows about RefCounted objects
            (they will be released and the excise listener removed).
         */
        void clearListeners() {
            boost::mutex::scoped_lock lk(listeners_mutex);
            inClear = true;

            for(typename std::set<Listener*>::iterator i = listeners.begin();
                i != listeners.end();
                i++)
            {
                if(RefCounted* rc = dynamic_cast<RefCounted*>(*i)) {
                    rc->removeExciseListener(this);
                    rc->release();
                }
            }
            listeners.clear();

            inClear = false;
        }

        /** For each listener, queues up a task to deliver the
            supplied event.  Note that these tasks are added to the
            default TaskQueue and as such will be delivered in a
            separate thread.  This means there is no guarantee that
            then event delivery will have have completed (or even
            started) by the time this method returns!

            @param e the event to be distributed
         */
        void distributeEvent(Event* e) {
            boost::mutex::scoped_lock lk(listeners_mutex);

            if (async) {
                for(typename std::set<Listener*>::iterator i = listeners.begin();
                    i != listeners.end();
                    i++)
                {
                    TaskQueue::defaultTQ().addTask(new ListenerTask<Listener, Event>(*i, e));
                }
            } else {
                std::set<Listener*> templisteners = listeners;

                lk.unlock();

                for(typename std::set<Listener*>::iterator i = templisteners.begin();
                    i != templisteners.end();
                    i++)
                {
                    e->deliverTo(*i);
                }
            }
        }

        /** Callback called by RefCounted::excise() indicating the
            supplied object wants to go away.  This remove the object
            from the listener list.

            @param object
         */
        void notifyObjectExcise(RefCounted* object) {
            if(Listener* l = dynamic_cast<Listener*>(object)) {
                removeListener(l);
            }
        }

        /** @return the number of listeners */
        unsigned int listenerCount() {
            boost::mutex::scoped_lock lk(listeners_mutex);
            return listeners.size();
        }

        /** @return true if the supplied object is present in the
            listener list
            @param l the listener in question
         */
        bool hasListener(Listener* l) {
            boost::mutex::scoped_lock lk(listeners_mutex);
            return (listeners.count(l) > 0);
        }

        /** @return true if event distribution is asynchronous.  If
            true event callbacks are pushed onto the task queue and
            distributeEvents() returns immediatly.  This should never
            block and is the default behavior.  If false, it will call
            event listeners synchronously in the thread of the caller
            (potentially blocking).

         */
        bool getAsynchronousEvents() {
            return async;
        }

        /** @param b True if event distribution is asynchronous.  If
            true event callbacks are pushed onto the task queue and
            distributeEvents() returns immediatly.  This should never
            block and is the default behavior.  If false, it will call
            event listeners synchronously in the thread of the caller
            (potentially blocking).

         */
        void setAsynchronousEvents(bool b) {
            async = b;
        }
    };
}

#endif