contain.h

开源代码的pwlib的1.10.0版本,使用openh323的1.18.0版本毕备

/*
 * contain.h
 *
 * Umbrella include for Container Classes.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: contain.h,v $
 * Revision 1.65  2005/11/25 03:43:47  csoutheren
 * Fixed function argument comments to be compatible with Doxygen
 *
 * Revision 1.64  2004/04/15 22:44:52  csoutheren
 * Re-applied gcc 2.95 patch as CVS screwed up
 *
 * Revision 1.63  2004/04/14 23:34:52  csoutheren
 * Added plugin for data access
 *
 * Revision 1.61  2004/04/12 00:36:04  csoutheren
 * Added new class PAtomicInteger and added Windows implementation
 *
 * Revision 1.60  2004/04/11 06:15:27  csoutheren
 * Modified to use Atomic_word if available
 *
 * Revision 1.59  2004/04/11 02:55:17  csoutheren
 * Added PCriticalSection for Windows
 * Added compile time option for PContainer to use critical sections to provide thread safety under some circumstances
 *
 * Revision 1.58  2004/04/09 03:42:34  csoutheren
 * Removed all usages of "virtual inline" and "inline virtual"
 *
 * Revision 1.57  2003/09/17 05:41:58  csoutheren
 * Removed recursive includes
 *
 * Revision 1.56  2003/09/17 01:18:02  csoutheren
 * Removed recursive include file system and removed all references
 * to deprecated coooperative threading support
 *
 * Revision 1.55  2003/03/31 01:23:56  robertj
 * Added ReadFrom functions for standard container classes such as
 *   PIntArray and PStringList etc
 *
 * Revision 1.54  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.53  2001/02/13 04:39:08  robertj
 * Fixed problem with operator= in container classes. Some containers will
 *   break unless the copy is virtual (eg PStringStream's buffer pointers) so
 *   needed to add a new AssignContents() function to all containers.
 *
 * Revision 1.52  1999/11/30 00:22:54  robertj
 * Updated documentation for doc++
 *
 * Revision 1.51  1999/08/22 12:13:42  robertj
 * Fixed warning when using inlines on older GNU compiler
 *
 * Revision 1.50  1999/08/17 03:46:40  robertj
 * Fixed usage of inlines in optimised version.
 *
 * Revision 1.49  1999/03/09 02:59:49  robertj
 * Changed comments to doc++ compatible documentation.
 *
 * Revision 1.48  1999/02/16 08:07:11  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.47  1998/09/23 06:20:23  robertj
 * Added open source copyright license.
 *
 * Revision 1.46  1997/07/08 13:15:04  robertj
 * DLL support.
 *
 * Revision 1.45  1996/08/17 10:00:20  robertj
 * Changes for Windows DLL support.
 *
 * Revision 1.44  1996/08/08 10:08:41  robertj
 * Directory structure changes for common files.
 *
 * Revision 1.43  1995/06/17 11:12:26  robertj
 * Documentation update.
 *
 * Revision 1.42  1995/03/14 12:41:13  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.41  1995/01/09  12:36:18  robertj
 * Removed unnecesary return value from I/O functions.
 * Changes due to Mac port.
 *
 * Revision 1.40  1994/12/13  11:50:45  robertj
 * Added MakeUnique() function to all container classes.
 *
 * Revision 1.39  1994/12/12  10:16:18  robertj
 * Restructuring and documentation of container classes.
 * Renaming of some macros for declaring container classes.
 * Added some extra functionality to PString.
 * Added start to 2 byte characters in PString.
 * Fixed incorrect overrides in PCaselessString.
 *
 * Revision 1.38  1994/12/05  11:18:58  robertj
 * Moved SetMinSize from PAbstractArray to PContainer.
 *
 * Revision 1.37  1994/11/28  12:33:44  robertj
 * Added dummy parameter for cls* constructor in containers. This prevents some very
 * strange an undesirable default construction of clones.
 *
 * Revision 1.36  1994/10/30  11:50:09  robertj
 * Split into Object classes and Container classes.
 * Changed mechanism for doing notification callback functions.
 *
 * Revision 1.35  1994/10/23  04:40:50  robertj
 * Made container * constractor protected.
 * Shorted OS Error assert.
 * Added printf constructor to PString.
 *
 * Revision 1.34  1994/09/25  10:36:41  robertj
 * Improved const behavious of container class macros.
 *
 * Revision 1.33  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.32  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.31  1994/08/21  23:43:02  robertj
 * Changed parameter before variable argument list to NOT be a reference.
 * Added object serialisation classes.
 *
 * Revision 1.30  1994/08/04  11:51:39  robertj
 * Rewrite of memory check functions.
 *
 * Revision 1.29  1994/07/27  05:58:07  robertj
 * Synchronisation.
 *
 * Revision 1.28  1994/07/25  03:33:50  robertj
 * Extra memory tests.
 *
 * Revision 1.27  1994/07/17  10:46:06  robertj
 * Added functions to strings in containers.
 *
 * Revision 1.26  1994/07/02  03:03:49  robertj
 * Addition of container searching facilities.
 *
 * Revision 1.25  1994/06/25  11:55:15  robertj
 * Unix version synchronisation.
 *
 * Revision 1.24  1994/04/20  12:17:44  robertj
 * Added code to assert
 *
 * Revision 1.23  1994/04/11  14:17:27  robertj
 * Made standard operators new and delete only declared for GNU C++
 *
 * Revision 1.22  1994/04/01  14:09:46  robertj
 * Removed PDECLARE_ABSTRACT_CONTAINER.
 * Added string stream class.
 * Added string containers.
 *
 * Revision 1.21  1994/03/07  07:38:19  robertj
 * Major enhancementsacross the board.
 *
 * Revision 1.20  1994/01/13  08:42:29  robertj
 * Fixed missing copy constuctor and assignment operator for PString.
 *
 * Revision 1.19  1994/01/13  05:33:41  robertj
 * Added contructor to get caseless string from ordinary string.
 *
 * Revision 1.18  1994/01/03  04:42:23  robertj
 * Mass changes to common container classes and interactors etc etc etc.
 *
 * Revision 1.17  1993/12/31  06:40:34  robertj
 * Made inlines optional for debugging purposes.
 * Added default to DeleteObjects() function.
 *
 * Revision 1.16  1993/12/24  04:20:52  robertj
 * Mac CFront port.
 *
 * Revision 1.15  1993/12/16  00:51:46  robertj
 * Made some container functions const.
 *
 * Revision 1.14  1993/12/15  21:10:10  robertj
 * Changes to fix inadequate reference system for containers.
 *
 * Revision 1.13  1993/12/14  18:44:56  robertj
 * Added RemoveAll() to collection classes.
 * Fixed incorrect destruction of objects in containers.
 *
 * Revision 1.12  1993/12/04  05:23:58  robertj
 * Added more string functions
 *
 * Revision 1.11  1993/09/27  16:35:25  robertj
 * Fixed bug in sorted lists.
 * Changed simple function for array of strings to a constructor.
 * Capitalised all macros.
 *
 * Revision 1.10  1993/08/27  18:17:47  robertj
 * Fixed bug with default number of elements in a collection.
 * Added missing Compare function to PAbstractSortedList
 * Added inline keywords for CFront compatibility.
 *
 * Revision 1.9  1993/08/21  01:50:33  robertj
 * Made Clone() function optional, default will assert if called.
 *
 * Revision 1.8  1993/08/19  18:00:32  robertj
 * Added two more standard base array classes
 *
 * Revision 1.7  1993/08/01  14:05:27  robertj
 * Added const to ToLower() and ToUpper() in the PString class.
 *
 * Revision 1.6  1993/07/16  14:40:55  robertj
 * Added PString constructor for individual characters.
 * Added string to C style literal format.
 *
 * Revision 1.5  1993/07/15  05:02:57  robertj
 * Removed redundant word in PString enum for string types.
 *
 * Revision 1.4  1993/07/15  04:23:39  robertj
 * Added constructor to PString to allow conversion from other string formats.
 * Fixed problem with variable parameter lists in sprintf() functions.
 *
 * Revision 1.3  1993/07/14  12:49:16  robertj
 * Fixed RCS keywords.
 *
 */

#ifndef _CONTAIN_H
#define _CONTAIN_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptlib/object.h>
#include <ptlib/critsec.h>

///////////////////////////////////////////////////////////////////////////////
// Abstract container class

/** Abstract class to embody the base functionality of a {\it container}.

Fundamentally, a container is an object that contains other objects. There
are two main areas of support for tha that are provided by this class. The
first is simply to keep a count of the number of things that the container
contains. The current size is stored and accessed by members of this class.
The setting of size is determined by the semantics of the descendent class
and so is a pure function.

The second area of support is for reference integrity. When an instance of
a container is copied to another instance, the two instance contain the
same thing. There can therefore be multiple references to the same things.
When one reference is destroyed this must {\bf not} destroy the contained
object as it may be referenced by another instance of a container class.
To this end a reference count is provided by the PContainer class. This
assures that the container only destroys the objects it contains when there
are no more references to them.

In support of this, descendent classes must provide a #DestroyContents()#
function. As the normal destructor cannot be used, this function will free
the memory or unlock the resource the container is wrapping.