Essential Tools Module User’s Guide
Chapter 1 Introduction
1.1 Overview
1.2 Features and Benefits
1.3 Examples
1.4 Products and Services Information
Chapter 2 Class Overview
2.1 Introduction
2.2 Class Groups
2.2.1 Date and Time Class Group
2.2.2 String Processing Class Group
2.2.3 Virtual Stream Class Group
2.2.4 Collection Class Group
2.2.5 Internationalization Class Group
2.2.6 File System Classes
2.2.7 Miscellaneous Class Group
2.3 Abstract and Concrete Classes
2.3.1 Concrete Classes
2.3.1.1 Simple Classes
2.3.1.2 Template-based Collection Classes
2.3.2 Abstract Base Classes
2.4 Common Functionality Among Classes
2.4.1 Common Member Functions
2.4.1.1 Persistence Functions
2.4.1.2 Store Size Functions
2.4.1.3 Stream I/O Functions
2.4.1.4 Comparison Functions
2.4.2 Memory Allocation and Deallocation
2.4.3 Information Flow
2.4.4 Multithread Safety
2.4.4.1 Assigning Thread Safety Levels to Classes and Libraries
2.4.4.2 Thread Safety in the Essential Tools Module
2.4.5 Indexing
2.4.6 Version
Chapter 3 Date and Time Classes
3.1 Introduction
3.2 Calendar and Time Formats
3.3 International Standards for Dates and Times
3.3.1 SourcePro’s ISO 8601 Parsers
3.4 Setting the Time Zone
3.5 RWDateTime
3.5.1 About Two or Four Digit Years
3.5.2 Member Functions
3.5.3 RWDateTime Sentinels
3.5.3.1 The “Invalid” Sentinel and Other Invalid Instances
3.5.3.2 The “Null” Sentinel
3.5.3.3 The Past and Future Sentinels
3.5.3.4 User-Defined Sentinels
3.6 RWDate
3.7 RWTime (deprecated)
3.8 The Date and Time Collectable Class
Chapter 4 String Processing Classes
4.1 Introduction
4.2 RWCString and RWWString
4.3 An Introductory Example
4.4 Lexicographic Comparisons
4.5 Substrings
4.6 Pattern Matching
4.6.1 Regular Expressions
4.6.1.1 The RWTRegex<T> Interface
4.6.1.2 Using Regular Expressions Efficiently
4.6.1.3 Introductory Examples Using Regular Expressions
4.7 String I/O
4.7.1 Iostreams
4.7.2 Virtual Streams
4.8 Tokenizer
4.9 Multibyte Strings
4.10 Wide Character Strings
4.11 Performance Considerations
Chapter 5 Stream Classes
5.1 Introduction
5.2 RWvios, RWvistream, and RWvostream
5.3 Specializing Virtual Streams
5.4 Simple Virtual Streams Example
5.5 Virtual Steams Recap
5.6 RWAuditStreamBuffer
5.7 Compressed IOStreams
5.7.1 Buffer Size
5.7.2 Typedefs
5.7.3 Custom Compressor Interface
Chapter 6 Collection Classes
6.1 Introduction
6.2 Collection Class Groups
6.2.1 Traditional Collection Classes
6.2.2 STL-based Collection Classes
6.2.3 STL Extension-based Collection Classes
6.2.4 RWCollectable Classes
6.3 Storage Methods of Collection Classes
6.3.1 Value-based and Reference-based Collections
6.3.2 Examples of Value-based and Reference-based Collections
6.3.3 A Note on Memory Management
6.4 Copying Collection Classes
6.4.1 Copying Reference-based Collection Classes
6.4.2 Copying Value-based Collection Classes
6.5 Retrieving Objects in Collections
6.5.1 Retrieval Methods
6.6 Iterators in Collection Classes
6.6.1 Traditional Essential Tools Module Iterators
6.7 Collection Class Templates
6.8 Template Overview
6.8.1 Template Naming Convention
6.8.2 Value vs. Reference Semantics in Templates
6.8.2.1 An Important Distinction
6.8.3 Intrusive Lists in Templates
6.9 Essential Tools Module Templates and C++ Standard Library Containers
6.9.1 The C++ Standard Library Containers
6.9.2 Commonality of Interface
6.10 Parameter Requirements
6.11 Function Objects for Comparison
6.11.1 More on Total Ordering
6.12 Function Objects for Hashing and Equality
6.13 Iterators in Class Templates
6.13.1 C++ Standard Library Iterators
6.13.2 Map-Based Iteration and Pairs
6.13.3 Iterators as Generalized Pointers
6.14 Iterators and the std() Gateway
6.15 Example Using the Essential Tools Module with the C++ Standard Library
6.16 Designing an RWCollectable Class
6.16.1 Bus Example Scenario
6.16.1.1 Serialization Support Macros
6.16.1.2 Exporting Symbols in a Windows Environment
6.16.2 The Role of RWCollectable
6.16.3 Bus Example Code
6.17 Creating an RWCollectable Object
6.17.1 Define a Default Constructor
6.17.2 Add RW_DECLARE_COLLECTABLE_CLASS() to your Class Declaration
6.17.3 Provide a Class Identifier for Your Class
6.17.3.1 Virtual Function isA()
6.17.3.2 Virtual Function newSpecies()
6.17.3.3 Function stringID()
6.17.4 Add Definitions for Virtual Functions
6.17.4.1 Virtual Function compareTo()
6.17.4.2 Virtual Function isEqual()
6.17.4.3 Virtual Function hash()
6.17.4.4 An Example of compareTo(), isEqual(), and hash()
6.17.5 Object Destruction
6.17.6 How to Add Polymorphic Persistence
6.17.6.1 Virtual Functions saveGuts(RWFile&) and saveGuts(RWvostream&)
6.17.6.2 Virtual Functions restoreGuts(RWFile&) and restoreGuts(RWvistream&)
6.17.6.3 Multiply-referenced Objects
6.17.6.4 Virtual Function binaryStoreSize()
6.17.6.5 Polymorphically Persisting Custom Collections
6.17.7 A Note on the RWFactory
6.18 Complete Listing for Class Bus
6.19 Smalltalk‑like Collection Classes
6.19.1 Tables of the Smalltalk-like Classes
6.19.2 Example
6.19.3 Choosing a Smalltalk-like Collection Class
6.19.3.1 Bags Versus Sets Versus Hash Tables
6.19.3.2 Sequenceable Classes
6.19.3.3 Dictionaries
6.19.4 Virtual Functions Inherited From RWCollection
6.19.4.1 insert()
6.19.4.2 find() and Friends
6.19.4.3 remove() Functions
6.19.4.4 apply() Functions
6.19.4.5 Functions clear() and clearAndDestroy()
6.19.5 Other Functions Shared by All RWCollections
6.19.5.1 Class Conversions
6.19.5.2 Inserting and Removing Other Collections
6.19.5.3 Selection
6.19.6 Virtual Functions Inherited from RWSequenceable
6.19.7 A Note on How Objects are Found
6.19.7.1 Hashing
Chapter 7 Internationalization Classes
7.1 Introduction
7.2 Localizing Alphabets with RWCString and RWWString
7.3 Challenges of Localizing Currencies, Numbers, Dates, and Times
7.4 RWLocale and RWZone
7.4.1 RWLocaleSnapshot and RWAnsiLocale
7.4.2 Dates
7.4.3 Time
7.4.4 Numbers
7.4.5 Currency
Chapter 8 Persistence
8.1 Introduction
8.2 Levels of Persistence
8.2.1 A Note About Terminology
8.2.2 About the Examples in this Section
8.3 No Persistence
8.4 Simple Persistence
8.4.1 Two Examples of Simple Persistence
8.4.1.1 Example One: Simple Persisting Objects of Fundamental Type
8.4.1.2 Example Two: Simple Persistence and Pointers
8.5 Isomorphic Persistence
8.5.1 Isomorphic versus Simple Persistence
8.5.2 Isomorphic Persistence of an Essential Tools Module Class
8.5.3 Designing Your Class to Use Isomorphic Persistence
8.5.3.1 Make All Necessary Class Data Available
8.5.3.2 Add RW_DECLARE_PERSISTABLE to Your Header File
8.5.3.3 Add RW_DEFINE_PERSISTABLE to One Source File
8.5.3.4 Check for Possible Problems
8.5.3.5 Define rwSaveGuts and rwRestoreGuts
8.5.4 Writing rwSaveGuts and rwRestoreGuts Functions
8.5.4.1 Guidelines for Writing rwSaveGuts
8.5.4.2 Guidelines for Writing rwRestoreGuts
8.5.5 Isomorphic Persistence of a User-designed Class
8.6 Polymorphic Persistence
8.6.1 Operators
8.6.2 Designing your Class to Use Polymorphic Persistence
8.6.3 Polymorphic Persistence Example
8.6.3.1 Example One: Saving Polymorphically
8.6.3.2 Example Two: Restoring Polymorphically
8.6.3.3 Example Two Revisited
8.6.3.4 Choosing Which Persistence Operator to Use
8.7 A Few Friendly Warnings
8.7.1 Always Save an Object by Value Before Saving the Identical Object by Pointer
8.7.2 Don't Save Distinct Objects with the Same Address
8.7.3 Don't Use Sorted RWCollections to Store Heterogeneous RWCollectable Objects
8.7.4 Define All RWCollectable Objects To Restore
Chapter 9 Error Handling and Reporting
9.1 Introduction
9.2 Error Categories
9.2.1 The Essential Tools Module Error Model
9.2.2 Internal Errors
9.2.2.1 Non-recoverable Internal Errors
9.2.2.2 Recoverable Internal Errors
9.2.3 External Errors
9.3 Error Reporting and Error Handling
9.3.1 Essential Tools Module Exception Architecture
9.3.1.1 RWxmsg
9.3.1.2 RWExternalErr
9.3.1.3 RWStreamErr
9.3.1.4 RWFileErr
9.3.1.5 RWxalloc
9.3.1.6 RWInternalErr
9.3.1.7 RWRegexErr
9.3.1.8 RWBoundsErr
9.3.2 Using the Error Reporting Classes to Handle Errors
9.3.2.1 When Exceptions are Supported
9.3.2.2 When Exceptions are Not Supported
9.4 The Debug Version of the Essential Tools Module
Chapter 10 File System Classes
10.1 Introduction
10.2 RWFile
10.2.1 Example
10.3 RWFileStat
10.3.1 Construction
10.3.2 Example
10.4 RWDirectoryIterator
10.4.1 Flat Iteration Example
10.4.2 Recursive Iteration Example
10.5 RWFileManager
10.5.1 Construction
10.5.2 Member Functions
10.5.3 Example
10.6 RWBTreeOnDisk
10.6.1 Construction
10.6.2 Example
Chapter 11 Scope Guard Classes
11.1 Introduction
11.2 RWScopeGuard
11.2.1 Construction
11.2.2 Member Functions
11.3 RWTRefHolder<T>
11.3.1 Why Use RWTRefHolder<T>
11.3.2 A Note on Pointer and Reference Parameters
11.4 Example
Chapter 12 Advanced Topics
12.1 Introduction
12.2 Copy on Write
12.2.1 A More Comprehensive Example
12.3 RWStringID
12.3.1 Duration of Identifiers
12.3.2 Programming with RWStringIDs
12.3.3 Implementation Details of RWStringID
12.3.3.1 Automatic RWClassIDs
12.3.3.2 Implementing Virtuals Via Statics
12.3.3.3 Polymorphic Persistence
12.3.3.4 Efficiency
12.3.3.5 Identification Collisions
12.4 More on Storing and Retrieving RWCollectable Objects
12.5 Multiple Inheritance
12.6 Using Custom Allocators
12.6.1 Template Functions
12.6.2 Example
Chapter 13 Common Mistakes
13.1 Introduction
13.2 Redefinition of Virtual Functions
13.3 Iterators
13.4 Return Type of operator>>()
13.5 Avoid Persisting Value Collections of Pointers
13.6 Include Path
13.7 Match Memory Models and Other Qualifiers
13.8 Keep Related Methods Consistent
13.8.1 DLL
13.9 Use the Capabilities of the Module!
Appendix A Choosing a Collection
A.1 Introduction
A.2 Selecting an Essential Tools Module Collection Class
A.2.1 How to Use the Decision Tree
A.2.2 Additional Selection Criteria
A.3 Time and Space Considerations
A.3.1 RWTBitVec<Size>, RWTPtrVector, and RWTValVector<T>
A.3.2 Singly-Linked Lists
A.3.3 Doubly-Linked Lists
A.3.4 Ordered Vectors
A.3.5 Sorted Vectors
A.3.6 Stacks and Queues
A.3.7 Deques
A.3.8 Binary Tree
A.3.9 (multi)map and (multi)set family
A.3.10 RWBTree, RWBTreeDictionary
A.3.11 Hash-based Collections
Appendix B Constants, Typedefs, Pointers, and Enumerations
B.1 Constants
B.2 Typedefs
B.3 Pointers to Functions
B.4 Enumerations
B.5 Standard Smalltalk Interface Typedefs
Internationalization Module User’s Guide
Chapter 1 Introduction
1.1 Welcome
1.2 Product Overview
1.3 Products and Services Information
Chapter 2 Concepts
2.1 Overview
2.2 Basic Terminology
2.3 Representing Text in Computers
2.3.1 Abstract Characters
2.3.2 Character Sets
2.3.3 Coded Character Sets
2.3.4 Character Encoding Forms
2.3.5 Character Encoding Schemes
2.3.6 Character Map
2.4 The Unicode Standard
2.4.1 Unicode Coded Character Set
2.4.2 Unicode Character Encoding Forms
2.4.3 Unicode Character Encoding Schemes
2.5 The ISO-10646 Standard
2.6 Multilingual Text in C++
Chapter 3 Character and String Processing
3.1 Overview
3.2 Representing Characters
3.3 Character Properties
3.3.1 Valid Code Points
3.3.2 Surrogate Pairs
3.3.3 Character Blocks
3.3.4 Character Scripts
3.3.5 General Character Categories
3.3.6 Character Names
3.3.7 Character Directionality
3.3.8 Character Width
3.3.9 Combining Classes
3.3.10 Character Case
3.3.11 Character Mirroring
3.3.12 Numeric Values
3.4 Representing Strings
3.4.1 RWBasicUString and RWCString
3.4.2 Memory Management in RWBasicUString
3.4.2.1 Creating and Using Deallocators
3.4.2.2 Null Termination
3.4.3 RWUString and RWBasicUString
3.4.4 Creating an RWUString
3.4.5 Converting to Unicode
3.4.6 Converting from Unicode
3.4.7 Escape Sequences
3.4.8 String Length
3.4.9 Comparing Strings
3.4.10 Accessing SubStrings
3.5 Iterating Over Strings
3.5.1 Accessing Code Points with Iterators
3.5.2 Modifying Code Points with Iterators
Chapter 4 Conversion
4.1 Overview
4.2 Character Encodings
4.2.1 Listing Encoding Names
4.2.2 Listing Encoding Name Aliases
4.2.3 Listing Encoding Name Standards
4.3 Explicit Conversions
4.3.1 Creating Converters
4.3.2 Explicitly Converting to Unicode
4.3.3 Explicitly Converting from Unicode
4.3.4 Conversion Errors
4.3.5 Saving and Restoring the Error Response State
4.3.6 Resetting Converters
4.4 Implicit Conversions
4.4.1 The Conversion Context Stacks
4.4.2 Creating Conversion Contexts
4.4.3 Implicitly Converting to Unicode
4.4.4 Implicitly Converting from Unicode
4.4.5 Bidirectional Conversions
Chapter 5 Normalization
5.1 Introduction
5.2 Character Equivalence
5.2.1 Canonical Equivalence
5.2.2 Compatibility Equivalence
5.3 Normalization Forms
5.4 Using RWUNormalizer
5.4.1 Normalizing Strings
5.4.2 Detecting the Normalization Form of a String
Chapter 6 Collation
6.1 Overview
6.2 Locale-Sensitive String Comparison
6.3 Customizing a Collator
6.3.1 Finding Collation Elements
6.3.2 Forming Collation Weights
6.3.2.1 Case Order
6.3.2.2 Punctuation Shifting
6.3.3 Examining Collation Levels
6.3.3.1 Collation Strength
6.3.3.2 Case Level
6.3.3.3 French Collation
6.4 Using Collation Keys
6.4.1 Using RWUCollationKey
6.4.2 Sorting Strings with Collation Keys
Chapter 7 Boundary Analysis and Tokenizing
7.1 Overview
7.2 Boundary Analysis
7.2.1 Creating an RWBreakSearch
7.2.2 Using an RWBreakSearch
7.2.3 Direct Queries
7.3 Tokenizing
7.3.1 Creating an RWUTokenizer
7.3.2 Specifying Delimiters
7.3.3 Extracting Tokens
7.3.3.1 Using the Function Call Operator
7.3.3.2 Using the nextToken() Method
Chapter 8 Pattern Matching
8.1 Overview
8.2 Lexical String Searching
8.3 Locale-Sensitive String Searching
8.3.1 Creating an RWUStringSearch
8.3.2 Iteration-Style Searches
8.3.3 Direct Queries
8.3.4 Search and Replace
8.4 Regular Expression String Searching
8.4.1 A Note on Support by UTR Version Number
8.4.2 POSIX Extended Regular Expression Syntax
8.4.3 Unicode Regular Expressions
8.4.3.1 Basic Unicode Regular Expression Extensions
8.4.3.2 Tailored Unicode Regular Expression Extensions
8.4.3.3 How to Use Tailored Regular Expressions
8.4.4 How to Create an RWURegularExpression
8.4.5 Searching for Pattern Matches
8.4.6 Manipulating Match Results
8.4.7 Replacing Pattern Matches
8.4.8 Iterating Over Pattern Matches
Chapter 9 Error Handling and Debugging
9.1 Overview
9.2 Exceptions
9.3 Execution Tracing
9.4 Compiling in Debug Mode
Chapter 10 Locales and Localized Resources
10.1 Overview
10.2 Named Locales
10.2.1 Listing Language Codes
10.2.2 Listing Country Codes
10.2.3 Listing Available Locales
10.3 Locale Objects
10.3.1 Creating Locales
10.3.2 Using Locales
10.3.3 The Default Locale
10.4 Localized Resources
10.4.1 The Resource Hierarchy
10.4.2 Defining Resource Bundles
10.4.3 Compiling Resource Bundles
10.4.4 Packaging Resource Bundles
10.4.5 Retrieving a Resource Bundle
10.4.6 Accessing a Resource
Chapter 11 Advanced Topics
11.1 Overview
11.2 Working in a Multithreaded Environment
11.3 Accessing ICU Constructs
Chapter 12 Glossary
Advanced Tools Module User’s Guide
PART I Advanced Tools Module
Chapter 1 Introduction
1.1 Welcome
1.2 Product Packages and Libraries
1.3 Examples
1.4 Products and Services Information
Chapter 2 Package Overview
2.1 Advanced Tools Module Packages
2.1.1 The Streams Package
2.1.2 The Serialization Package
2.1.3 The Types Package
2.2 Using the Packages Together
2.3 Introduction to the Handle-Body Architecture
PART II Advanced Tools Module Packages
Chapter 3 The Streams Package
3.1 Introducing the Streams Package
3.2 The Stream Families
3.2.1 Memory Streams
3.2.2 Interpackage Dependencies
3.3 Definitions
3.4 Streams Package Architecture
3.4.1 The Common Framework
3.4.1.1 The Handle Classes
3.4.1.2 The Abstract Body Classes
3.4.2 The Extended Framework
3.4.2.1 The Memory Stream Handle Classes
3.4.2.2 The Memory Stream Abstract Body Classes
3.4.2.3 The Memory Stream Concrete Body Classes
3.4.3 The Common Filtered Streams
3.4.3.1 Buffered Streams
3.4.3.2 Synchronized Streams
3.4.3.3 Guarded Streams
3.5 The Streams Package Classes
3.5.1 The Binary Streams
3.5.1.1 The RWByteToStreambufOutputStreamImp Class
3.5.1.2 The RWByteFromStreambufInputStreamImp Class
3.5.1.3 The RWStreambufToByteOutputStream Class
3.5.1.4 The RWStreambufFromByteInputStream Class
3.5.2 The Narrow Character Streams
3.5.2.1 The RWCharToStreambufOutputStreamImp Class
3.5.2.2 The RWCharFromStreambufInputStreamImp Class
3.5.2.3 The RWStreambufToCharOutputStream Class
3.5.2.4 The RWStreambufFromCharInputStream Class
3.5.3 The Unicode Character Streams
3.5.3.1 The RWUCharToByteOutputStreamImp Class
3.5.3.2 The RWUCharFromByteInputStreamImp Class
3.5.3.3 The RWUCharToUTF8ByteOutputStreamImp Class
3.5.3.4 The RWUCharFromUTF8ByteInputStreamImp Class
3.5.4 The Wide Character Streams
3.5.4.1 The RWWCharToWStreambufOutputStreamImp Class
3.5.4.2 The RWWCharFromWStreambufInputStreamImp Class
3.5.5 The Data Streams
3.5.5.1 The RWNativeDataToByteOutputStreamImp Class
3.5.5.2 The RWNativeDataFromByteInputStreamImp Class
3.5.5.3 The RWOstreamDataToCharOutputStreamImp Class
3.5.5.4 The RWIstreamDataFromCharInputStreamImp Class
3.5.5.5 The RWvostreamToDataOutputStream Class
3.5.5.6 The RWvistreamFromDataInputStream Class
Chapter 4 Using Streams
4.1 Introduction
4.1.1 The Streams Header Files
4.1.2 Using the Streams Package with Other Streaming Libraries
4.1.2.1 Using the Standard iostreams Library
4.1.2.2 Using Essential Tools Module Virtual Streams
4.2 Examples
4.2.1 Creating and Using Streams with Only One Streaming Element
4.2.2 Creating and Using Chains of Streaming Elements
4.2.2.1 Output Example
4.2.2.2 Input Example
4.2.3 Creating and Using Thread-safe Chains of Streaming Elements
4.2.3.1 Creating a Synchronized Data Output Stream
4.2.3.2 Creating and Managing Threads Using Active Objects
4.2.3.3 Creating and Sharing a Synchronized Data Output Stream Among Several Active Objects
4.2.3.4 Active Objects and Data Input Streams
4.2.3.5 Creating and Sharing a Synchronized Data Input Stream Among Several Active Objects
4.2.4 Creating and Using Stream Adapter Classes in the Advanced Tools Module
4.2.4.1 The iostreams Adapter Classes
4.2.4.2 Virtual Streams Adapter Classes in the Essential Tools Module
4.2.4.3 Architecture of the Adapter Classes
4.2.4.4 Using the Adapter Classes for Output
4.2.4.5 Using the Adapter Classes for Input
4.3 Error Handling
4.3.1 Handling Errors Using the Stream Status Functions
4.3.2 Streams Package Exception Classes
Chapter 5 The Serialization Package
5.1 Introducing the Serialization Package
5.1.1 Classes Supported by the Serialization Package
5.1.2 Object Serialization for Saving Program State
5.1.3 Object Serialization and Distributed Applications
5.1.4 Interpackage Dependencies
5.2 Object Serialization Concepts
5.2.1 Writing and Reading the Object State
5.2.2 Type Information (Polymorphism)
5.2.3 Object Identity (Isomorphism)
5.2.4 Intrusive and External Serialization
5.2.5 Symmetry of Object Input and Output
5.2.6 Annotated Streams and Embedded Schemas
5.3 Supported Streaming Formats
5.3.1 The Compact Object Stream Format
5.3.1.1 Object Streams With Data Streams
5.3.1.2 Object Streams With Virtual Streams
5.3.1.3 Object Streams With Collectable Objects
5.4 Serialization Package Architecture
5.4.1 How Does Serialization Work?
5.4.2 Relationship to the Streams Package
5.4.3 Handle-Body Architecture
5.5 Serialization Package Classes
Chapter 6 Using Object Serialization
6.1 Introduction
6.1.1 Including the Header Files
6.2 Getting Started
6.2.1 Serialization Requirements
6.2.2 Simple Examples
6.2.2.1 Declaring the Streaming Operators
6.2.2.2 Defining the streamContents() Function
6.2.2.3 Streaming the Serialized Object
6.2.2.4 Writing to and Reading from Compact Object Streams
6.2.2.5 Writing to and Reading from Compact Object Streams With Virtual Streams
6.3 Using the Stream Contents Macros
6.3.1 Header File Macros
6.3.2 Source File Macros
6.3.3 Macros for External Serialization
6.3.4 Macro Summary
6.4 Basic Examples
6.4.1 Saving and Restoring an Object by Value
6.4.1.1 First Change
6.4.1.2 Second Change
6.4.2 Saving and Restoring an Object by Pointer
6.4.2.1 First Change
6.4.2.2 Second Change
6.4.2.3 Third Change
6.4.2.4 A Caution on Using Streaming Pointers
6.4.3 Associations with Other Objects
6.4.3.1 Data Member is an Object
6.4.3.2 Data Member is a Pointer to an Object
6.4.3.3 Data Member is a Value-based or Pointer-based Collection
6.4.4 Templates
6.4.5 Default Constructors
6.4.6 External Serialization
6.4.7 External Serialization of Templates and Nested Classes
6.5 Advanced Examples
6.5.1 Using Object Streams with RWCollectable-Derived Objects
6.5.2 Making RWCollectable Objects That Are Also Serializable
6.5.3 Writing Custom streamContents() Functions
6.5.4 Controlling the Scope of Object Reference Resolution
6.5.4.1 Streaming Out Multiple Objects
6.5.4.2 Streaming Multiple Objects into One Document
Chapter 7 The Types Package
7.1 Introducing the Types Package
Chapter 8 International Features of the Advanced Tools Module
8.1 Introduction
8.1.1 An Introduction to Unicode
8.2 Determining your Character Encoding Needs
8.2.1 The Advanced Tools Module’s Character Encoding Requirements
8.2.2 When You Do Not Need the Internationalization Module
8.2.3 When You Do Need the Internationalization Module
8.2.4 Choosing the Appropriate String Class
8.3 International Features of the Streams Package
8.3.1 Using the Streams Package without the Internationalization Module
8.3.1.1 Unicode-Based Stream Classes
8.3.1.2 Unicode Converter Classes
8.3.1.3 Example
8.3.2 Using the Streams Package with the Internationalization Module
8.4 International Features of the Serial Package
8.4.1 Using the Serial Package without the Internationalization Module
8.4.1.1 Compact Object Streams
8.4.2 Using the Serial Package with the Internationalization Module
8.4.2.1 Converting from a Local Encoding to UTF-16
8.4.2.2 Converting from UTF-16 to a Local Encoding
XML Streams Module User’s Guide
Chapter 1 Introduction
1.1 Welcome
1.2 Product Features
1.2.1 The XML Streams Module Package
1.3 Dependencies
1.3.1 Basic Software Dependencies
1.3.2 Optional Software Dependencies
1.3.3 Schema Dependencies
1.4 Products and Services Information
Chapter 2 Using XML Streams
2.1 Overview
2.2 Types of Streams
2.3 When to Use XML Streams
Chapter 3 A Simple XML Streams Use Case
3.1 Introduction
3.2 Use Case Description
3.3 Serialization Requirements
3.4 Examining the Code
3.4.1 Declaring the Basic Classes
3.4.2 Making the Basic Classes Serializable
3.4.2.1 Header File Changes
3.4.2.2 Source File Changes
3.4.3 Persisting the Serializable Objects
Chapter 4 Enhanced Streams
4.1 Introduction
4.2 The Difference Between Enhanced Streams and Basic Streams
4.2.1 Comparison Example of Basic XML Streams with Enhanced XML Streams
4.3 Example
4.3.1 Example Discussion
4.3.2 Serializing the book Object to a File
4.3.3 Restoring the book Object
4.3.4 Examining the XML Output
Chapter 5 Performing Transformations
5.1 Introduction
5.1.1 Character-based C++ Transformations
5.1.2 Element-based Transformations
5.2 Transforming your XML Documents
5.2.1 Overview of the Transformation Process
5.2.2 Adding Serialization Support
5.2.3 Serializing the book Object to a File
5.2.3.1 For a Character-based C++ Transformation
5.2.3.2 For an Element-based C++ Transformation
5.2.4 Restoring the book Object
5.2.4.1 For a Character-based C++ Transformation
5.2.4.2 For an Element-based C++ Transformation
5.2.5 Examining the XML Output
5.2.5.1 For a Character-based C++ Transformation
5.2.5.2 For an Element-based C++ Transformation
5.3 Discussion
Chapter 6 XSLT Transformations
6.1 Introduction
6.1.1 Your XSLT Processor
6.1.2 The XSLT Transformation Procedure
6.2 Creating the Objects and Streams
6.2.1 Defining a Transformation Object
6.2.2 Defining a Character Transformation Stream
6.2.3 Defining an XSLT Transformation Stream
6.2.3.1 Defining the XSLT Transformation Input Stream
6.2.3.2 Defining the XSLT Transformation Output Stream
6.3 Performing the Transformation
6.3.1 Serializing the book Object to a File
6.3.2 Restoring the book Object
6.3.3 Examining the XML Output
Chapter 7 International Features of the XML Streams Module
7.1 Introduction
7.1.1 An Introduction to Unicode
7.2 Determining your Character Encoding Needs
7.2.1 Deciding if You Need the Internationalization Module
7.2.1.1 When You Do Not Need the Internationalization Module
7.2.1.2 When You Do Need the Internationalization Module
7.2.2 The XML Streams Package Character Encoding Requirements
7.2.2.1 Narrow Character Interfaces
7.2.2.2 Wide and Unicode Character Interfaces
7.3 Using the XML Streams Package without the Internationalization Module
7.3.1 Choosing the Appropriate String Class Interface
7.3.2 Converting to and from UTF-8 and UTF-16
7.3.2.1 Converting RWCStrings and RWBasicUStrings
7.3.2.2 Converting RWWStrings to and from UTF-8
7.4 Using the XML Streams Package with the Internationalization Module
7.4.1 Output Stream Example
7.4.2 Input Stream Example
Threads Module User’s Guide
PART I Introduction
Chapter 1 Introduction
1.1 Welcome
1.2 Packages and Libraries
1.3 Examples
1.4 Products and Services Information
Chapter 2 Threads Module Overview
2.1 Background
2.2 The Threads Module Packages
2.2.1 Threading Package
2.2.2 Synchronization Package
2.2.3 Interthread Communication Package
2.2.4 Smart Pointer Package
2.2.5 Functor Package
2.2.6 Execution Tracing Package
2.2.7 Thread-compatible Exception Package
2.3 Using the Packages Together
PART II Concurrency Packages
Chapter 3 The Threading Package
3.1 Introducing the Threading Package
3.1.1 Interpackage Dependencies
3.1.2 Including the Header Files
3.2 Definitions
3.2.1 Threads and Concurrency
3.2.2 Threads and Memory
3.2.3 Thread Safety
3.3 Threading Class Hierarchies
3.3.1 The Runnable Class Hierarchy
3.3.1.1 Runnable Handle Classes
3.3.1.2 Runnable Body Classes
3.3.1.3 Thread Pool Class
3.3.2 The Attribute Class Hierarchy
3.3.3 The IOU Class in the Threading Package
3.4 Using Threads
3.4.1 Creating Threads
3.4.2 Introducing the Runnable
3.4.3 Explicitly Constructing Functors and Runnables
3.5 The Runnable Object Classes
3.5.1 Defining a Runnable’s Task
3.5.1.1 Functor-Based Runnables
3.5.1.2 Runnable Servers
3.5.1.3 Guard Functors
3.5.2 Creating Functor-based Runnables
3.5.3 Runnable State
3.5.4 Runnable Operations
3.5.5 Starting a Runnable
3.5.5.1 Starting Synchronous Runnables
3.5.5.2 Checking the Completion State
3.5.5.3 Starting Threaded Runnables
3.5.5.4 Distinguishing Between Synchronous and Threaded Runnables
3.5.5.5 Restarting a Threaded Runnable
3.5.6 Joining a Runnable
3.5.6.1 Types of Join Functions
3.5.6.2 Joining Unstarted or Inactive Runnables
3.5.7 Monitoring the Completion State of a Runnable
3.5.8 Catching and Rethrowing Exceptions
3.5.8.1 Testing After Successful Joins
3.5.8.2 Types of Rethrown Exceptions
3.5.9 Interrupting a Runnable
3.5.9.1 Avoiding Deadlock
3.5.9.2 Interrupting a Runnable from Another Thread
3.5.9.3 Completing the Interrupt Request
3.5.9.4 Types of requestInterrupt() Functions
3.5.9.5 Shutting Down a Continuous Process
3.5.9.6 Rendezvous Synchronization
3.5.9.7 Interrupting Threads at Startup
3.5.10 Canceling a Runnable
3.5.10.1 Canceling a Runnable from Another Thread
3.5.10.2 Completing a Cancellation Request
3.5.10.3 Aborting a Cancellation
3.5.10.4 Types of requestCancellation Functions
3.5.10.5 Undoing a Cancellation Request
3.5.10.6 Using Synchronization Classes to Service Cancellation Requests
3.5.10.7 Designing Your Code
3.5.11 Sleeping
3.5.12 Yielding Execution
3.5.12.1 Executing Under a Preemptive Scheduling Policy
3.5.12.2 Yielding to Lower Priority Threads
3.5.13 Suspending and Resuming Execution
3.5.13.1 Using the suspend() and resume() Functions
3.5.13.2 Deciding Whether Suspension Is Available
3.5.14 Terminating Execution
3.5.15 Monitoring the Execution State of a Runnable
3.5.15.1 Getting the Instantaneous Execution State of a Runnable
3.5.15.2 Monitoring Changes in Execution State
3.5.15.3 Using Wait Functions
3.5.15.4 Using Callbacks
3.5.15.5 Registering the Callback
3.5.15.6 Changing the Execution State
3.5.15.7 Reusing Functors
3.5.15.8 Removing a Callback
3.5.16 Execution Nesting
3.5.16.1 Starting Synchronous Runnables
3.5.16.2 Using the Nested Runnable Information
3.5.17 Thread Identification
3.6 The Server Classes
3.6.1 Constructing a Server
3.6.2 Starting a Server
3.6.3 Enqueuing Runnables on a Server
3.6.4 Stopping a Server
3.6.5 Interrupting a Server
3.6.6 Canceling a Server
3.6.7 Using Server Pool Thread Attributes
3.6.8 Resizing a Server Pool
3.6.8.1 Contracting a Server Pool
3.6.8.2 Creating or Expanding a Server Pool
3.7 The Thread Pool Class
3.7.1 Constructing a Thread Pool
3.7.2 Starting a Thread Pool
3.7.3 Enqueuing Work on a Thread Pool
3.7.4 Stopping a Thread Pool
3.7.5 Considerations
3.7.5.1 Pool Thread Attributes
3.7.5.2 Pool Expansion and Contraction
3.8 Using Threads To Build Active Objects
3.8.1 Using Runnables
3.8.1.1 Example
3.8.1.2 Other Solutions to the Join Problem
3.8.2 Using Runnable Servers
3.9 Thread Attributes
3.9.1 Thread Attribute Families
3.9.1.1 Scheduling Attributes
3.9.1.2 Stack Management Attributes
3.9.2 Thread Attribute Portability
3.9.3 Testing For Support
3.9.3.1 Using Feature Test Macros
3.9.3.2 “Get” Test Functions
3.9.3.3 “Set” Test Functions
3.9.3.4 “Is Set” Test Functions
3.9.4 Querying Attribute Values
3.9.5 Setting Attribute Values
3.9.6 Default Attribute Values
3.9.7 Restoring Default Attribute Values
3.9.8 Determining the Legal Range For An Attribute
3.9.9 Scheduling Attributes
3.9.9.1 Start Policy
3.9.9.2 Scheduling Contention Scope
3.9.9.3 Scheduling Inheritance Policy
3.9.9.4 Concurrency Policy
3.9.9.5 Scheduling Policy
3.9.9.6 Scheduling Priority
3.9.9.7 Scheduling Time-Slice Quantum
3.9.10 Stack Attributes
3.9.10.1 Allocating and Managing a Thread Stack
3.9.10.2 System-Managed Stack Attributes
3.9.10.3 User-Managed Stack Attributes
3.9.11 Initializing Threaded Runnables
3.9.11.1 Supplying RWThreadAttribute Instances To Threaded Runnables
3.9.11.2 Supplying RWThreadAttribute Instances At Construction
3.9.11.3 Supplying RWThreadAttribute Instances After Construction
3.9.12 Querying Threaded Runnables For Thread Creation Attributes
Chapter 4 The Synchronization Package
4.1 Introducing the Synchronization Package
4.1.1 Interpackage Dependencies
4.1.2 Including the Header Files
4.2 Definitions
4.3 Synchronization Class Hierarchy
4.3.1 The Synchronization Class Hierarchy
4.3.2 The Guard Class Hierarchy
4.4 Getting Started
4.4.1 Creating Two or More Threads that Access the Same Resources
4.4.2 Using Mutexes
4.4.2.1 Using a Basic Mutex Mechanism
4.4.2.2 Using a Try-Catch Block
4.4.3 Using Guards
4.4.4 Building Monitors
4.4.4.1 Count Synchronization
4.4.4.2 Read Synchronization
4.4.4.3 The RWTMonitor<Lock> Class
4.4.5 Using Condition Variables
4.4.5.1 Combining the Condition Variable with Mutual Exclusion
4.4.5.2 Using the Condition Variable for Producer-Consumer Synchronization
4.5 The Synchronization Classes
4.5.1 The RWMutexLock Class
4.5.1.1 Avoiding a Block
4.5.1.2 Using Timed Waits
4.5.1.3 Attempting Recursive Acquisition
4.5.1.4 Acquiring Mutex Ownership
4.5.1.5 Using a Guard Class
4.5.1.6 Initializing a Mutex
4.5.1.7 Servicing Cancellation Requests
4.5.2 The RWFIFOMutexLock Class
4.5.3 The RWNullMutexLock Class
4.5.4 The RWTRecursiveLock Class
4.5.4.1 Identifying Threads
4.5.4.2 Using RWTRecursiveLock
4.5.5 The RWReadersWriterLock Class
4.5.6 The RWCriticalSection Class
4.5.7 The RWSemaphore Class
4.5.8 The RWCondition Class
4.5.9 The RWBarrier Class
4.5.10 The RWTMonitor Class
4.6 The Guard Classes
4.6.1 Using a Lock Guard
4.6.2 Releasing and Reacquiring a Guarded Lock
4.6.3 Using the Unlock Guard Class
4.6.4 Using the RWTTryLockGuard Template Class
4.6.5 Using Classes with Read-Write Synchronization Resources
Chapter 5 The Interthread Communication Package
5.1 Introducing the Interthread Communication Package
5.1.1 Interpackage Dependencies
5.1.2 Including the Header Files
5.2 Definitions
5.2.1 Futures, IOUs, and Escrows
5.2.2 Producers, Consumers, and Blocking
5.3 Interthread Communication Class Hierarchies
5.3.1 The Producer-Consumer Class Hierarchy
5.3.2 The IOU Class Hierarchy
5.4 Using Interthread Communication
5.4.1 Using Producer-Consumer Queues
5.4.1.1 The RWTPCValQueue Family of Classes
5.4.1.2 Example
5.5 The IOU Classes
5.5.1 Testing for Empty IOU Handles
5.5.2 Constructing an IOU
5.5.3 Closing an IOU
5.5.3.1 The close() Function
5.5.3.2 The setException() Function
5.5.3.3 Example
5.5.4 Redeeming an IOU
5.5.4.1 Rules about Threads and IOUs
5.5.4.2 Aborting a Request
5.5.4.3 Querying the Status of an IOU Object
5.5.5 Using IOUs
5.5.5.1 Example
5.5.5.2 Closing and Redeeming an IOU
5.5.5.3 Using Active Objects
5.5.6 Waiting for IOUs
5.5.6.1 Asynchronous Example
5.5.7 Trapping IOUs with RWTIOUTrap
5.5.7.1 Waiting for Trapped IOUs
5.5.7.2 Using Timed Waits
5.5.7.3 Improving the Asynchronous Example
5.5.7.4 Another Asynchronous Example
5.6 The Producer‑Consumer Classes
5.6.1 Value and Pointer Classes
5.6.2 Guarded and Prioritized Classes
PART III Foundation Packages
Chapter 6 The Execution Tracing Package
6.1 Introducing the Execution Tracing Package
6.1.1 Interpackage Dependencies
6.1.2 Including the Trace Header Files
6.1.3 Trace Severity Levels
6.2 Execution Tracing Package Architecture
6.2.1 The Trace Output Pipeline
6.2.2 Trace Class Hierarchy
6.3 Using Trace
6.4 Using Set Declaration Macros
6.4.1 Package Declaration Macros
6.4.2 Class Declaration Macros
6.4.2.1 Implications for Template Classes
6.4.3 Function Declaration Macros
6.4.3.1 Macros for Global Functions
6.4.3.2 Macros for Member Functions
6.4.3.3 Macros for Static Member Functions
6.4.3.4 Macros for Friend Functions
6.4.3.5 Implications for Template Classes
6.4.3.6 Assigning functionTag Names
6.4.4 Setting Environment Variables for Event Sets
6.5 Using Event Generation Macros
6.5.1 Macros for Global Functions
6.5.2 Macros for Member Functions
6.5.3 Including Variables in Trace Messages
6.5.4 Trace Macros Example
6.6 Using the Trace Manager
6.6.1 The Trace Manager Buffer
6.6.2 Stopping Trace
6.6.3 Trace Manager Environment Variables
6.7 Using Trace Clients
6.7.1 Using the Predefined Client
6.7.2 Creating User-defined Clients
6.7.2.1 Including a Timestamp in Trace Output
6.7.2.2 Including Thread IDs in Trace Output
6.7.2.3 Using Your Client
6.8 Using Trace Filters
6.8.1 Using the Predefined Filters
6.8.1.1 Using RWTraceLevelFilter
6.8.1.2 Using RWTraceMultiClientFilter
6.8.2 Chaining Multiple Filters
6.8.3 Creating User-defined Filters
6.8.3.1 Creating the Filter’s Body Class
6.8.3.2 Creating the Filter’s Handle Class
6.8.3.3 Instantiating Your Derived Filter
6.9 Using Package-level Tracing
6.10 Controlling Trace Output
6.10.1 The RW_USER_TRACE_LEVEL Macro
6.10.2 The RW_TRACE_LEVEL Environment Variable
6.10.3 The RWTraceLevelFilter Class
6.10.4 Combining All Filtering Methods
Chapter 7 The Smart Pointer Package
7.1 Introducing the Smart Pointer Package
7.1.1 Interpackage Dependencies
7.1.2 Including the Smart Pointer Header Files
7.2 Smart Pointer Class Hierarchy
7.2.1 Template Parameter Naming Conventions
7.2.2 Handle-Body Classes in Class Hierarchies
7.3 Using the Handle-Body Classes
7.3.1 Understanding the Handle-Body Idiom
7.3.1.1 Simplifying Memory Management
7.3.1.2 Decomposing Complex Abstractions
7.3.1.3 Decoupling Interfaces from Implementations
7.3.1.4 Handle-Body Mechanics
7.3.2 Implementing Your Own Handles and Bodies
7.3.2.1 Defining Handle Classes that Automatically Create Bodies
7.3.2.2 Defining Handle Classes that Don’t Create Bodies
7.3.2.3 Handle-Body Example
7.4 Using the RWTSingleton Class
7.5 Using the Smart Pointer Classes
7.5.1 Using RWTOnlyPointer
7.5.2 Using RWTCountedPointer
7.5.2.1 Deriving from RWTCountingBody for Reference Counting
7.5.3 Using RWTCountingPointer
7.5.3.1 Providing RWTCountingPointer with a Counter
7.6 Smart Pointer Class Architecture
Chapter 8 The Functor Package
8.1 Introducing the Functor Package
8.1.1 Interpackage Dependencies
8.1.2 Including the Functor Header Files
8.1.3 What Are They For?
8.1.4 How Do They Work?
8.1.4.1 When the Function Signature Matches the Functor Invocation
8.1.4.2 When Function Arguments Won’t Change Across Invocations
8.1.4.3 When You’re Not Using a Return Value
8.1.4.4 When the Types Don’t Quite Match
8.2 Constructing Functors
8.2.1 Analyzing Functor Requirements
8.2.2 Copying and Assigning Functors
8.3 Invoking Functors
8.3.1 Running Unknown Functions
8.4 Binding Functor Arguments
8.4.1 Binding Reference Types
8.4.2 Binding Member Functions
8.4.3 Using Placeholder Arguments
Chapter 9 The Thread‑compatible Exception Package
9.1 Introducing the Thread-compatible Exception Package
9.1.1 Interpackage Dependencies
9.1.2 Including the Exception Header Files
9.2 Exception Class Hierarchy
9.3 Default Exception Messages
9.4 Using the Thread-compatible Exception Classes
9.4.1 Creating Your Own Exception Classes
9.4.2 Creating Your Own Error Handler
9.4.3 Making Existing Exceptions Thread-Compatible
PART IVResources
Appendix A Acknowledgements
A.1 People
A.2 Citations
Threads Module Platform Guide
Chapter 1 Introduction
1.1 Overview
1.2 Examples
1.3 Products and Services Information
Chapter 2 AIX Technical Information
2.1 AIX Thread Attributes: An Overview
2.2 AIX POSIX 1003.1c Thread Attribute Support
2.2.1 Scheduling Attributes
2.2.1.1 Start Policy
2.2.1.2 Contention Scope
2.2.1.3 Scheduling Inheritance Policy
2.2.1.4 Concurrency Policy
2.2.1.5 Scheduling Policy
2.2.1.6 Scheduling Priority
2.2.1.7 Scheduling Time-Slice Quantum
2.2.2 Stack Attributes
2.2.2.1 System-Managed Stack Attributes
2.2.2.2 User-Managed Stack Attributes
Chapter 3 HP‑UX Technical Information
3.1 HP-UX Thread Attributes: An Overview
3.2 HP-UX POSIX 1003.1c Thread Attribute Support
3.2.1 Scheduling Attributes
3.2.1.1 Start Policy
3.2.1.2 Contention Scope
3.2.1.3 Scheduling Inheritance Policy
3.2.1.4 Concurrency Policy
3.2.1.5 Scheduling Policy
3.2.1.6 Scheduling Priority
3.2.1.7 Scheduling Time-Slice Quantum
3.2.2 Stack Attributes
3.2.2.1 System-Managed Stack Attributes
3.2.2.2 User-Managed Stack Attributes
Chapter 4 Linux Technical Information
4.1 Linux Threading Environments
4.2 Linux Thread Attributes: An Overview
4.3 Linux POSIX 1003.1c Thread Attribute Support
4.3.1 Scheduling Attributes
4.3.1.1 Start Policy
4.3.1.2 Contention Scope
4.3.1.3 Scheduling Inheritance Policy
4.3.1.4 Concurrency Policy
4.3.1.5 Scheduling Policy
4.3.1.6 Scheduling Priority
4.3.1.7 Scheduling Time-Slice Quantum
4.3.2 Stack Attributes
4.4 GNU LinuxThreads
Chapter 5 Solaris Technical Information
5.1 Solaris Threading APIs
5.2 Solaris Thread Attributes: An Overview
5.3 Solaris Threads Attribute Support
5.3.1 Scheduling Attributes
5.3.1.1 Start Policy
5.3.1.2 Scheduling Contention Scope
5.3.1.3 Scheduling Inheritance Policy
5.3.1.4 Concurrency Policy
5.3.1.5 Scheduling Policy
5.3.1.6 Scheduling Priority
5.3.1.7 Scheduling Time-Slice Quantum
5.3.2 Stack Attributes
5.3.2.1 System-Managed Stack Attributes
5.3.2.2 User-Managed Stack Attributes
5.3.3 Signal Handling Considerations
Chapter 6 Windows Technical Information
6.1 Win32 Thread Attribute Support
6.1.1 Scheduling Attributes
6.1.1.1 Start Policy
6.1.1.2 Scheduling Contention Scope
6.1.1.3 Scheduling Inheritance Policy
6.1.1.4 Concurrency Policy
6.1.1.5 Scheduling Policy
6.1.1.6 Scheduling Priority
6.1.1.7 Scheduling Time-Slice Quantum
6.1.2 Stack Attributes
6.1.2.1 System-Managed Stack Attributes
6.1.2.2 User-Managed Stack Attributes
6.2 Using the Threads Module with MFC
Essential Tools Module User’s Guide
6.2 Using the Threads Module with MFC