samples/safetest/overview.cxx

   1 /*
   2  * overview.cxx
   3  *
   4  * Thread safety test of PSafeXXX structures
   5  *
   6  * Copyright (c) 2005 Indranet Technologies Ltd.
   7  *
   8  * The contents of this file are subject to the Mozilla Public License
   9  * Version 1.0 (the "License"); you may not use this file except in
  10  * compliance with the License. You may obtain a copy of the License at
  11  * http://www.mozilla.org/MPL/
  12  *
  13  * Software distributed under the License is distributed on an "AS IS"
  14  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  15  * the License for the specific language governing rights and limitations
  16  * under the License.
  17  *
  18  * The Original Code is Open Phone Abstraction Library.
  19  *
  20  * The Initial Developer of the Original Code is Indranet Technologies Ltd.
  21  *
  22  * The author of this code is Derek J Smithies
  23  * *
  24  * $Log$
  25  * Revision 1.1  2006/02/12 21:42:07  dereksmithies
  26  * Add lots of doxygen style comments, and an introductory page.
  27  *
  28  *
  29  */
  30
  31 /*! \mainpage Thread safe test of PSafeXXX
  32
  33 \section secOverview Overview
  34
  35      An application to test the operation of the methods in the
  36      PSafeXXX structures of Pwlib. Specifically, we examine
  37      PSafeObject, PSafeDictionary, PSafePtr.
  38
  39      In addition, we examine the PThread structure, because hundreds
  40      of PThread instances are are created/destroyed every minute.
  41
  42 \version 1.0
  43
  44 \author  Derek J Smithies
  45
  46
  47 $Date$
  48
  49
  50 \section secContents Contents
  51
  52 \li \ref secClassListings
  53 \li \ref secArchitecture
  54
  55 \section secClassListings Description of the classes in this application
  56 The following classes are to be found in this application.
  57 \li SafeTest - the parent class of everything, which is descended from
  58      PProcess, and contains the dictionary being tested.
  59 \li DelayThread - the worker class, is descended from PSafeObject, and is
  60     placed in the dictionary being tested
  61 \li UserInterfaceThread - waits for keyboard input and responds appropriately
  62 \li LauncherThread - creates instances of the DelayThread class
  63 \section secArchitecture Architecture
  64
  65 The DelayThread class is the "worker bee" class in this
  66 application. Hundreds, or indeed millions of instances of this class
  67 will be created and destroyed. Each DelayThread instance is descended from
  68  PSafeObject and does the following things
  69  \li create an AutoDeletedThread to
  70  \li appends this DelayThread instance to a dictionary
  71  \li sleep for the user defined  number of milliseconds
  72  \li create an AutoDeletedThread to remove this DelayThread
  73      instance from the dictionary.
  74
  75 There are several threads of execution in this program
  76
  77 \li Launcher thread, which runs in the class LauncherThread. There is
  78    one instance of this thread, which runs in a busy loop fashion to
  79    create DelayThread instances. This launcher thread will create
  80    DelayThread instances when the internal counter of the number of
  81    instances falls below a user defined values.
  82 \li UserInterface thread, which runs in the class
  83     UserInterfaceThread. This reads input from the console, and will
  84     report on the progress, (number of iterations, average delay
  85     period etc) and will end the program on request.
  86 \li Garbage collection thread, which runs inside several methods of
  87     the SafeTest class. It follows the examples in pwlib of repeatedly
  88     calling the method dictionary.DelateObjectsToBeDeleted. It
  89     deviates from these examples by having no delay between calling
  90     the DeleteObjects method.
  91
  92 This program is ideally run on a multi processor machine. When run,
  93 you will see two threads are consuming 100% of the cpu time, and that
  94 there are several other threads that just "come and go". The idea is
  95 that after some time we expect it to be running just as at the
  96 beginning. No thread will stop with an error condition, and the user
  97 interface will still behave as expected.
  98 */