Public API Reference

csutil/cseventq.h

Go to the documentation of this file.

/*
    Crystal Space 3D engine: Event Queue interface
    Copyright (C) 1998 by Andrew Zabolotny <bit@freya.etu.ru>
    Copyright (C) 2001 by Eric Sunshine <sunshine@sunshineco.com>
    Copyright (C) 2005 by Adam D. Bradley <artdodge@cs.bu.edu>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library 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
    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/

#ifndef __CS_CSEVENTQ_H__
#define __CS_CSEVENTQ_H__

#ifdef ADB_DEBUG /* debugging output... */
#include <iostream>
#endif

#include "csextern.h"

#include "csutil/array.h"
#include "csutil/hash.h"
#include "csutil/ref.h"
#include "csutil/refarr.h"
#include "csutil/scf_implementation.h"
#include "csutil/threading/rwmutex.h"
#include "csutil/weakref.h"
#include "csutil/eventhandlers.h"
#include "iutil/eventh.h"
#include "iutil/eventq.h"
#include "cssubscription.h"

struct iObjectRegistry;

class csEventCord;
class csEventOutlet;
class csPoolEvent;

#define DEF_EVENT_QUEUE_LENGTH  256

template<>
class csHashComputer<iEventHandler *> : public csHashComputerIntegral<iEventHandler *> {};

class CS_CRYSTALSPACE_EXPORT csEventQueue : 
  public scfImplementation1<csEventQueue, iEventQueue>
{
  friend class csEventOutlet;
  friend class csPoolEvent;
  friend class csEventTree;
  friend class csEventQueueTest;

private:
  // Shared-object registry
  iObjectRegistry* Registry;
  // Event name registry
  csRef<iEventNameRegistry> NameRegistry;
  // Event handler registry
  csRef<iEventHandlerRegistry> HandlerRegistry;
  // The queue itself (technically, a ring buffer)
  volatile iEvent** EventQueue;
  // Queue head and tail pointers
  volatile size_t evqHead, evqTail;
  // The maximum queue length
  volatile size_t Length;  
  // Event tree.  All subscription PO graphs and delivery queues hang off
  // of this.
  csEventTree *EventTree;
  // Shortcut to per-event-name delivery queues.
  csHash<csEventTree *,csEventID> EventHash;
  // Array of allocated event outlets.
  csArray<csEventOutlet*> EventOutlets;
  // Array of allocated event cords.
  csHash<csEventCord *, csEventID> EventCords;
  // Pool of event objects
  csPoolEvent* EventPool;
  csRefArray<iEventHandler> handlers;
  CS::Threading::ReadWriteMutex mutex;
  CS::Threading::ReadWriteMutex etreeMutex;

  // Enlarge the queue size.
  void Resize (size_t iLength);  
  // Send broadcast pseudo-events (bypassing event queue).
  void Notify (const csEventID &name);

  /*
   * Start a loop. The purpose of this function is to protect
   * against modifications to the Listeners array while this array
   * is being processed.
   */
  void StartLoop ();
  // End a loop.
  void EndLoop ();

  /* Internal variant of RemoveAllListeners() which optionally omits creation
     of a new event tree (in case of destruction) */
  void RemoveAllListeners (bool recreateEventTree);
public:

  csEventQueue (iObjectRegistry*, size_t iLength = DEF_EVENT_QUEUE_LENGTH);
  virtual ~csEventQueue ();

  virtual void Process ();
  virtual void Dispatch (iEvent&);

  virtual csHandlerID RegisterListener (iEventHandler*);
  virtual csHandlerID RegisterListener (iEventHandler *handler,
        const csEventID &event) 
  { 
    csHandlerID id = RegisterListener(handler);
    if (id!=CS_HANDLER_INVALID)
    {
      if (Subscribe(handler, event))
        return id;
      else
        RemoveListener(handler); /* fall through */
    }
    return CS_HANDLER_INVALID;
  }
  virtual csHandlerID RegisterListener (iEventHandler *handler,
        const csEventID events[]) 
  { 
    csHandlerID id = RegisterListener(handler);
    if (id!=CS_HANDLER_INVALID)
    {
      if (Subscribe(handler, events))
        return id;
      else
        RemoveListener(handler); /* fall through */
    }
    return CS_HANDLER_INVALID;
  }
  virtual bool Subscribe (iEventHandler*, const csEventID &);
  virtual bool Subscribe (iEventHandler*, const csEventID[]);
  virtual void Unsubscribe (iEventHandler*, const csEventID &);
  virtual void Unsubscribe (iEventHandler*, const csEventID[]);
  virtual void RemoveListener (iEventHandler*);
  virtual void RemoveAllListeners ();

  virtual csPtr<iEventOutlet> CreateEventOutlet (iEventPlug*);
  virtual iEventOutlet* GetEventOutlet ();
  virtual iEventCord* GetEventCord (const csEventID &);

  uint32 CountPool ();
protected:
  virtual iEvent *CreateRawEvent ();
public:
  virtual csPtr<iEvent> CreateEvent ();
  virtual csPtr<iEvent> CreateEvent (const csEventID &name, bool broadcast);
  virtual csPtr<iEvent> CreateEvent (const csEventID &name);
  virtual csPtr<iEvent> CreateEvent (const char *name);
  virtual csPtr<iEvent> CreateBroadcastEvent (const csEventID &name);
  virtual csPtr<iEvent> CreateBroadcastEvent (const char *name);
  virtual void Post (iEvent*);
  virtual csPtr<iEvent> Get ();
  virtual void Clear ();
  virtual bool IsEmpty () { return evqHead == evqTail; }

  csEventID Frame;
};

#endif // __CS_CSEVENTQ_H__

---