Changeset 4839 for branches/erijo-dev

Show
Ignore:
Timestamp:
01/27/07 21:08:39 (23 months ago)
Author:
erijo
Message:

Added an event queue class and added/updated comments

Location:
branches/erijo-dev/licq
Files:
5 added
12 modified

Legend:

Unmodified
Added
Removed

  • branches/erijo-dev/licq/licq/interface/event.h

    r4832 r4839  
    3232 
    3333class IEvent; 
     34 
     35/** \brief A smart pointer to an IEvent instance. 
     36    \ingroup public 
     37*/ 
    3438typedef boost::shared_ptr<IEvent> IEventPtr; 
    3539 
     40/** \interface IEvent 
     41    \ingroup public 
     42    \brief Represents an event in the system. 
     43 
     44    An event has a name, a sender id and any number of properties. 
     45*/ 
    3646class IEvent : private boost::noncopyable 
    3747{ 
    3848protected: 
     49  /// Destroy the event. 
    3950  virtual ~IEvent(); 
     51 
     52  /** \brief Internal function for retriving a pointer to the property. 
     53 
     54      \param[in] key The property to get. 
     55      \param[out] value Pointer set to the value if property is found. 
     56 
     57      \return True if property exists; otherwise false. 
     58  */ 
    4059  virtual bool getProperty(const std::string& key, const boost::any** value) const = 0; 
    4160 
    4261public: 
     62  /** \brief Create a new event. 
     63 
     64      \param[in] sender The sender's (or creator's) plugin id. 
     65      \param[in] eventName Name of the event. 
     66 
     67      \return The created event. 
     68  */ 
    4369  static IEventPtr create(TPluginId sender, const std::string& eventName); 
    4470 
     71  /** \return Sender id passed to create(). */ 
    4572  virtual TPluginId getSenderId() const = 0; 
     73 
     74  /** \return Event name passed to create(). */ 
    4675  virtual const std::string& getEventName() const = 0; 
    4776 
     77  /** \return True if the event has a property \a key; otherwise false. */ 
    4878  virtual bool hasProperty(const std::string& key) const = 0; 
    4979 
     80  /** \brief Set the value of a property. 
     81 
     82      Set the property \a key to \a value, overwriting any existing property 
     83      with the same name. 
     84 
     85      \param[in] key Property name. 
     86      \param[in] value Property value. 
     87  */ 
    5088  virtual void setProperty(const std::string& key, const boost::any& value) = 0; 
     89 
     90  /// Calls setProperty(key, std::string(value)). 
    5191  void setProperty(const std::string& key, const char* value); 
    5292 
     93  /** \brief A type safe method for getting a property value. 
     94 
     95      \param[in] key Name of the property to get. 
     96      \param[out] value Set to the property's value if property exists. 
     97 
     98      \return True if the property was found and was of the correct type; 
     99        otherwise false. 
     100  */ 
    53101  template<typename ValueType> 
    54102  bool getProperty(const std::string& key, ValueType* value) const; 

  • branches/erijo-dev/licq/licq/interface/log.h

    r4835 r4839  
    3232{ 
    3333 
     34/** \interface ILog 
     35    \ingroup public 
     36    \brief A printf-styled logging facility. 
     37*/ 
    3438class ILog 
    3539{ 
    … …  
    3741  enum LogType 
    3842  { 
     43    /// Basic information about what's going on. 
    3944    LogTypeInfo, 
     45    /// Warnings which are not critical but could be important. 
    4046    LogTypeWarning, 
     47    /// Critical errors which should be brought to the attention of the user. 
    4148    LogTypeError, 
     49    /// Fatal errors after which Licq is unable to continue running. 
    4250    LogTypeFatal, 
     51    /// Debugging aid. 
    4352    LogTypeDebug, 
     53    /// Packet dumps. 
    4454    LogTypePacket 
    4555  }; 
    4656 
     57  /// Destroy the log. 
    4758  virtual ~ILog(); 
    4859 
     60  /** \brief Log a printf-styled message. 
     61 
     62      \param[in] type Type of log message. 
     63      \param[in] format A printf-styled format string. 
     64      \param[in] ap Varying number of arguments, matching \a format. 
     65  */ 
    4966  virtual void log(LogType type, const char* format, va_list ap) = 0; 
    5067 
     68  /** \brief Log a printf-styled message. 
     69      \see log(). 
     70  */ 
    5171  void note(LogType type, const char* format, ...) CHECK_FORMAT(3, 4); 
    5272 
     73  /// Equivalent to calling note(ILog::LogTypeInfo, \a format, \a ...). 
    5374  void info(const char* format, ...) CHECK_FORMAT(2, 3); 
     75 
     76  /// Equivalent to calling note(ILog::LogTypeWarning, \a format, \a ...). 
    5477  void warning(const char* format, ...) CHECK_FORMAT(2, 3); 
     78 
     79  /// Equivalent to calling note(ILog::LogTypeError, \a format, \a ...). 
    5580  void error(const char* format, ...) CHECK_FORMAT(2, 3); 
     81 
     82  /// Equivalent to calling note(ILog::LogTypeFatal, \a format, \a ...). 
    5683  void fatal(const char* format, ...) CHECK_FORMAT(2, 3); 
     84 
     85  /// Equivalent to calling note(ILog::LogTypeDebug, \a format, \a ...). 
    5786  void debug(const char* format, ...) CHECK_FORMAT(2, 3); 
     87 
     88  /// Equivalent to calling note(ILog::LogTypePacket, \a format, \a ...). 
    5889  void packet(const char* format, ...) CHECK_FORMAT(2, 3); 
    5990}; 

  • branches/erijo-dev/licq/licq/types.h

    r4829 r4839  
    2727{ 
    2828 
     29/** \brief A list of strings. 
     30    \ingroup public 
     31*/ 
    2932typedef std::list<std::string> TStringList; 
     33 
     34/** \brief All plugins have an unique id of type TPluginId. 
     35    \ingroup public 
     36*/ 
    3037typedef unsigned long TPluginId; 
     38 
     39/** \brief All events get an unique id of type TEventId when they are sent to the daemon. 
     40    \ingroup public 
     41*/ 
    3142typedef unsigned long TEventId; 
    3243 

  • branches/erijo-dev/licq/src/CMakeLists.txt

    r4836 r4839  
    11set(licqdaemon_SRCS 
    22  event.cpp 
     3  eventqueue.cpp 
    34  logfile.cpp 
    45  version.cpp 

  • branches/erijo-dev/licq/src/event.h

    r4829 r4839  
    2929{ 
    3030 
     31/** \class TEvent 
     32    \ingroup internal 
     33    \brief An implementation of IEvent. 
     34*/ 
    3135class TEvent : public IEvent 
    3236{ 

  • branches/erijo-dev/licq/src/logfile.h

    r4836 r4839  
    2727{ 
    2828 
     29/** \class TLogFile 
     30    \ingroup internal 
     31    \brief An implementation of ILog that logs all message to file. 
     32*/ 
    2933class TLogFile : public ILog 
    3034{ 
    3135private: 
     36  /// File to log to. 
    3237  FILE* File; 
    3338 
    3439public: 
     40  /** \brief Constructs a new TLogFile. 
     41 
     42      \param[in] file An open file stream to log to. 
     43  */ 
    3544  TLogFile(FILE* file = stderr); 
    3645 

  • branches/erijo-dev/licq/src/logserializer.h

    r4835 r4839  
    2929{ 
    3030 
    31 /** Serialize logging, so multiple threads can safely use the same log backend. */ 
     31/** \class TLogSerializer 
     32    \ingroup internal 
     33    \brief An implementation of ILog that serialize logging for multiple threads. 
     34 
     35     By giving each thread a separate instance of TLogSerializer initialized with 
     36     the same log backend, multiple threads can log to the same log backend without 
     37     the backend having to be thread safe. 
     38 
     39     TLogSerializer implements the decorator design pattern. 
     40     \see http://en.wikipedia.org/wiki/Decorator_pattern 
     41*/ 
    3242class TLogSerializer : private boost::noncopyable, 
    3343                       public ILog 
    3444{ 
    3545private: 
     46  /// Mutex to serialize access. 
    3647  TMutex Mutex; 
     48 
     49  /// Log to log to. 
    3750  ILog* Log; 
    3851 
    3952public: 
     53  /// Creates a new TLogSerializer that logs to \a log. 
    4054  TLogSerializer(ILog* log); 
     55 
     56  // From ILog 
    4157  void log(LogType type, const char* format, va_list ap); 
    4258}; 

  • branches/erijo-dev/licq/src/tests/CMakeLists.txt

    r4836 r4839  
    11set(licqdaemontest_SRCS 
     2  eventqueuetest.cpp 
    23  eventtest.cpp 
    34  logfiletest.cpp 

  • branches/erijo-dev/licq/src/utils/dynamiclibrary.h

    r4829 r4839  
    2929{ 
    3030 
     31/** \class TDynamicLibrary 
     32    \ingroup internal 
     33    \brief Open dynamic libraries and load symbols. 
     34*/ 
    3135class TDynamicLibrary : private boost::noncopyable 
    3236{ 
    … …  
    3943 
    4044public: 
    41   /** Closes the dynamic library. */ 
     45  /** \brief Close the dynamic library. 
     46 
     47      Before calling the destructor, make absolutely sure that no symbols residing 
     48      in this library is still in use. Otherwise prepare for a crash. 
     49  */ 
    4250  ~TDynamicLibrary(); 
    4351 
    44   /** Open a dynamic library. 
     52  /** \brief Open a dynamic library. 
    4553 
    46       \param log The log to log errors to. 
    47       \param filename Library to open. See dlopen(3) for how this name is resolved. 
     54      \param[in] log The log to log errors to. 
     55      \param[in] filename Library to open. See dlopen(3) on your system for how 
     56        this name is resolved. 
    4857 
    4958      \return NULL on error; otherwise a new instance of TDynamicLibrary. 
    … …  
    5261  static TDynamicLibrary* open(ILog* log, const std::string& filename); 
    5362 
    54   /** Load a symbol from the library. 
     63  /** \brief Load a symbol from the library. 
    5564 
    5665      \param name Name of symbol to load. 

  • branches/erijo-dev/licq/src/utils/misc.h

    r4830 r4839  
    2424{ 
    2525 
    26 /** Utility to be used in standard algorithms. 
     26/** \struct ObjectDeleter 
     27    \brief Functor for deleting objects. 
     28    \ingroup internal 
     29 
     30    A common usage scenario: 
    2731    \code 
    2832    std::list<TObject*> ptrList; 
     33    // Fill ptrList with a lot of objects. 
    2934    std::for_each(ptrList.begin(), ptrList.end(), Licq::ObjectDeleter()); 
     35    ptrList.clear(); 
    3036    \endcode 
    3137*/ 
    3238struct ObjectDeleter 
    3339{ 
     40  /// Delete \a ptr. 
    3441  template<typename T> 
    3542  void operator()(const T* ptr) const 

  • branches/erijo-dev/licq/src/utils/mutex.h

    r4829 r4839  
    2727{ 
    2828 
     29/** \class TMutex 
     30    \ingroup internal 
     31    \brief A mutual exclusive device. 
     32 
     33    TMutex is a wrapper around pthread's mutex facility. 
     34*/ 
    2935class TMutex : private boost::noncopyable 
    3036{ 
    … …  
    3440 
    3541public: 
    36   /** Creates a new unlocked mutex. */ 
     42  /// Create a new unlocked mutex. 
    3743  TMutex(); 
    3844 
    39   /** Destroys the mutex, unlocking it if necessary. */ 
     45  /// Destroy the mutex, unlocking it if necessary. 
    4046  ~TMutex(); 
    4147 
    42   /** Locks the mutex. Blocks until the mutex is locked. */ 
     48  /// Lock the mutex. Blocks until the mutex is locked. 
    4349  void lock(); 
    4450 
    45   /** Unlocks the mutex. */ 
     51  /// Unlock the mutex. 
    4652  void unlock(); 
    4753 
    48   /** Tries to lock the mutex. 
     54  /** \brief Try to lock the mutex without blocking. 
     55 
    4956      \return True if the mutex was locked; otherwise false. 
    5057  */ 
    5158  bool tryLock(); 
    5259 
    53   /** Check if the mutex is locked. 
     60  /** \brief Check if the mutex is locked. 
    5461 
    55       Relying on the return value from this method is not recomended. Since, depending 
     62      Relying on the return value from this method is not recomended. Depending 
    5663      on how threads are scheduled, the return value may be invalid even before it 
    5764      has made it back to the caller. Better use tryLock(). 

  • branches/erijo-dev/licq/src/utils/mutexlocker.h

    r4829 r4839  
    2828{ 
    2929 
    30 /** A helper class that unlocks the mutex when it is destroyed. 
     30/** \class TMutexLocker 
     31    \ingroup internal 
     32    \brief Unlocks a locked mutex in the destructor. 
     33 
     34    A helper class that unlocks the mutex when it is destroyed. 
    3135    TMutexLocker is in itself not thread safe. Only use it as a convinient 
    32     way to have mutexes unlocked in case of e.g. exceptions. 
     36    way to have a mutex unlocked in case of e.g. an exception or multiple 
     37    return points. 
     38 
     39    \code 
     40    class TThreadSafeCounter 
     41    { 
     42    private: 
     43      TMutex Mutex; 
     44      int Counter; 
     45    public: 
     46      TThreadSafeCounter() : Counter(0) {} 
     47      int operator++(int) 
     48      { 
     49        TMutexLocker locker(&Mutex); 
     50        locker.lock(); 
     51        return Counter++; 
     52      } 
     53    }; 
     54    \endcode 
    3355*/ 
    3456class TMutexLocker : private boost::noncopyable 
    … …  
    3961 
    4062public: 
    41   /** \param mutex Must be a mutex \b not locked by this thread. */ 
     63  /** \brief Create a new TMutexLocker. 
     64 
     65      Does \b not lock \a mutex. 
     66 
     67      \param[in] mutex Must be a mutex \b not locked by this thread. 
     68  */ 
    4269  TMutexLocker(TMutex* mutex); 
    4370 
    44   /** Unlocks the mutex if it was previous locked by calling lock() or tryLock(). */ 
     71  /// Unlock the mutex if it was previous locked in lock() or tryLock(). 
    4572  ~TMutexLocker(); 
    4673 
    47   /** Locks the mutex. Blocks until the mutex is locked. */ 
     74  /// Lock the mutex. Blocks until the mutex is locked. 
    4875  void lock(); 
    4976 
    50   /** Unlocks the mutex. */ 
     77  /// Unlock the mutex. 
    5178  void unlock(); 
    5279 
    53   /** Tries to lock the mutex. 
     80  /** \brief Try to lock the mutex without blocking. 
     81 
    5482      \return True if the mutex was locked; otherwise false. 
    5583  */ 
    5684  bool tryLock(); 
    5785 
    58   /** Release the mutex. After this call, all operations will fail and the 
    59       destructor will not unlock the mutex. 
     86  /** \brief Release the mutex. 
     87 
     88      After this call, all operations will fail and the destructor will 
     89      not unlock the mutex. 
    6090  */ 
    6191  TMutex* releaseMutex();