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 <[email protected]>
    Copyright (C) 2001 by Eric Sunshine <[email protected]>
    Copyright (C) 2005 by Adam D. Bradley <[email protected]>

    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/thread.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;
  // Protection against multiple threads accessing same event queue
  csRef<csMutex> Mutex;
  // 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;

  // Enlarge the queue size.
  void Resize (size_t iLength);
  // Lock the queue for modifications: NESTED CALLS TO LOCK/UNLOCK NOT ALLOWED!
  inline void Lock () { Mutex->LockWait(); }
  // Unlock the queue
  inline void Unlock () { Mutex->Release(); }
  // 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 ();

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;
  csEventID PreProcess;
  csEventID ProcessEvent;
  csEventID PostProcess;
  csEventID FinalProcess;

  struct iTypedFrameEventDispatcher : public iEventHandler 
  {
  protected:
    csWeakRef<csEventQueue> parent;
    csEventID sendEvent;
  public:
    iTypedFrameEventDispatcher () 
    {
    }
    virtual ~iTypedFrameEventDispatcher ()
    {
    }
    CS_EVENTHANDLER_DEFAULT_INSTANCE_CONSTRAINTS
    virtual bool HandleEvent (iEvent&) 
    { 
      parent->Notify (sendEvent);
      return false;
    }
  };

  class PreProcessFrameEventDispatcher 
    : public scfImplementation2<PreProcessFrameEventDispatcher, 
                                csEventQueue::iTypedFrameEventDispatcher, 
                                scfFakeInterface<iEventHandler> > 
  {
  public:
    PreProcessFrameEventDispatcher (csEventQueue* parent) 
      : scfImplementationType (this)
    {
      iTypedFrameEventDispatcher::parent = parent;
      sendEvent = parent->PreProcess;
    }
    CS_EVENTHANDLER_PHASE_LOGIC("crystalspace.frame.preprocess")
  };
  
  class ProcessFrameEventDispatcher 
    : public scfImplementation2<ProcessFrameEventDispatcher, 
                                csEventQueue::iTypedFrameEventDispatcher, 
                                scfFakeInterface<iEventHandler> > 
  {
  public:
    ProcessFrameEventDispatcher (csEventQueue* parent) 
      : scfImplementationType (this)
    {
      iTypedFrameEventDispatcher::parent = parent;
      sendEvent = parent->ProcessEvent;
    }
    CS_EVENTHANDLER_PHASE_3D("crystalspace.frame.process")
  };

  class PostProcessFrameEventDispatcher 
    : public scfImplementation2<PostProcessFrameEventDispatcher, 
                                csEventQueue::iTypedFrameEventDispatcher, 
                                scfFakeInterface<iEventHandler> > 
  {
  public:
    PostProcessFrameEventDispatcher (csEventQueue* parent) 
      : scfImplementationType (this)
    {
      iTypedFrameEventDispatcher::parent = parent;
      sendEvent = parent->PostProcess;
    }
    CS_EVENTHANDLER_PHASE_2D("crystalspace.frame.postprocess")
  };
  
  class FinalProcessFrameEventDispatcher 
    : public scfImplementation2<FinalProcessFrameEventDispatcher, 
                                csEventQueue::iTypedFrameEventDispatcher, 
                                scfFakeInterface<iEventHandler> > 
  {
  public:
    FinalProcessFrameEventDispatcher (csEventQueue* parent) 
      : scfImplementationType (this)
    {
      iTypedFrameEventDispatcher::parent = parent;
      sendEvent = parent->FinalProcess;
    }
    CS_EVENTHANDLER_PHASE_FRAME("crystalspace.frame.finalprocess")
  };
};

#endif // __CS_CSEVENTQ_H__

---