namespace ost

EMACS ** Local variables: mode: c++ c-basic-offset: 8 End: More...

List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Types

Public Methods

Public Static Methods

Public Members


Detailed Description

EMACS ** Local variables: mode: c++ c-basic-offset: 8 End:

enum throw_t { THROW_NOTHING, THROW_OBJECT, THROW_EXCEPTION }

throw_t

typedef enum throw_t throw_t

throw_t

Thread (class)

Thread

Every thread of execution in an application is created by deriving a unique class from the Thread class and by implementing the Run method. The base Thread class supports encapsulation of the generic threading methods implemented on various target operating systems. This includes the ability to start and stop threads in a synchronized and controllable manner, the ability to specify thread execution priority, and thread specific "system call" wrappers, such as for sleep and yield. A thread exception is thrown if the thread cannot be created. Threading was the first part of Common C++ I wrote, back when it was still the APE library. My goal for Common C++ threading has been to make threading as natural and easy to use in C++ application development as threading is in Java. With this said, one does not need to use threading at all to take advantage of Common C++. However, all Common C++ classes are designed at least to be thread-aware/thread-safe as appropriate and necessary.

Common C++ threading is currently built either from the Posix "pthread" library or using the win32 SDK. In that the Posix "pthread" draft has gone through many revisions, and many system implementations are only marginally compliant, and even then usually in different ways, I wrote a large series of autoconf macros found in ost_pthread.m4 which handle the task of identifying which pthread features and capabilities your target platform supports. In the process I learned much about what autoconf can and cannot do for you..

Currently the GNU Portable Thread library (GNU pth) is not directly supported in Common C++. While GNU "Pth" doesn't offer direct native threading support or benefit from SMP hardware, many of the design advantages of threading can be gained from it's use, and the Pth pthread "emulation" library should be usable with Common C++. In the future, Common C++ will directly support Pth, as well as OS/2 and BeOS native threading API's.

Common C++ itself defines a fairly "neutral" threading model that is not tied to any specific API such as pthread, win32, etc. This neutral thread model is contained in a series of classes which handle threading and synchronization and which may be used together to build reliable threaded applications.

Common C++ defines application specific threads as objects which are derived from the Common C++ "Thread" base class. At minimum the "Run" method must be implemented, and this method essentially is the "thread", for it is executed within the execution context of the thread, and when the Run method terminates the thread is assumed to have terminated.

Common C++ allows one to specify the running priority of a newly created thread relative to the "parent" thread which is the thread that is executing when the constructor is called. Since most newer C++ implementations do not allow one to call virtual constructors or virtual methods from constructors, the thread must be "started" after the constructor returns. This is done either by defining a "starting" semaphore object that one or more newly created thread objects can wait upon, or by invoking an explicit "Start" member function.

Threads can be "suspended" and "resumed". As this behavior is not defined in the Posix "pthread" specification, it is often emulated through signals. Typically SIGUSR1 will be used for this purpose in Common C++ applications, depending in the target platform. On Linux, since threads are indeed processes, SIGSTP and SIGCONT can be used. On solaris, the Solaris thread library supports suspend and resume directly.

Threads can be canceled. Not all platforms support the concept of externally cancelable threads. On those platforms and API implementations that do not, threads are typically canceled through the action of a signal handler.

As noted earlier, threads are considered running until the "Run" method returns, or until a cancellation request is made. Common C++ threads can control how they respond to cancellation, using setCancellation(). Cancellation requests can be ignored, set to occur only when a cancellation "point" has been reached in the code, or occur immediately. Threads can also exit by returning from Run() or by invoking the Exit() method.

Generally it is a good practice to initialize any resources the thread may require within the constructor of your derived thread class, and to purge or restore any allocated resources in the destructor. In most cases, the destructor will be executed after the thread has terminated, and hence will execute within the context of the thread that requested a join rather than in the context of the thread that is being terminated. Most destructors in derived thread classes should first call Terminate() to make sure the thread has stopped running before releasing resources.

A Common C++ thread is normally canceled by deleting the thread object. The process of deletion invokes the thread's destructor, and the destructor will then perform a "join" against the thread using the Terminate() function. This behavior is not always desirable since the thread may block itself from cancellation and block the current "delete" operation from completing. One can alternately invoke Terminate() directly before deleting a thread object.

When a given Common C++ thread exits on it's own through it's Run() method, a "Final" method will be called. This Final method will be called while the thread is "detached". If a thread object is constructed through a "new" operator, it's final method can be used to "self delete" when done, and allows an independent thread to construct and remove itself autonomously.

A special global function, getThread(), is provided to identify the thread object that represents the current execution context you are running under. This is sometimes needed to deliver signals to the correct thread. Since all thread manipulation should be done through the Common C++ (base) thread class itself, this provides the same functionality as things like "pthread_self" for Common C++.

Common C++ threads are often aggregated into other classes to provide services that are "managed" from or operate within the context of a thread, even within the Common C++ framework itself. A good example of this is the TCPSession class, which essentially is a combination of a TCP client connection and a separate thread the user can define by deriving a class with a Run() method to handle the connected service. This aggregation logically connects the successful allocation of a given resource with the construction of a thread to manage and perform operations for said resource.

Threads are also used in "service pools". In Common C++, a service pool is one or more threads that are used to manage a set of resources. While Common C++ does not provide a direct "pool" class, it does provide a model for their implementation, usually by constructing an array of thread "service" objects, each of which can then be assigned the next new instance of a given resource in turn or algorithmically.

Threads have signal handlers associated with them. Several signal types are "predefined" and have special meaning. All signal handlers are defined as virtual member functions of the Thread class which are called when a specific signal is received for a given thread. The "SIGPIPE" event is defined as a "Disconnect" event since it's normally associated with a socket disconnecting or broken fifo. The Hangup() method is associated with the SIGHUP signal. All other signals are handled through the more generic Signal().

Incidently, unlike Posix, the win32 API has no concept of signals, and certainly no means to define or deliver signals on a per-thread basis. For this reason, no signal handling is supported or emulated in the win32 implementation of Common C++ at this time.

In addition to TCPStream, there is a TCPSession class which combines a thread with a TCPStream object. The assumption made by TCPSession is that one will service each TCP connection with a separate thread, and this makes sense for systems where extended connections may be maintained and complex protocols are being used over TCP.

enum thread_cancel_t { THREAD_CANCEL_INITIAL=0, THREAD_CANCEL_DEFERRED=1, THREAD_CANCEL_IMMEDIATE, THREAD_CANCEL_DISABLED, THREAD_CANCEL_DEFAULT=THREAD_CANCEL_DEFERRED }

thread_cancel_t

typedef enum thread_cancel_t thread_cancel_t

thread_cancel_t

enum thread_suspend_t { THREAD_SUSPEND_ENABLE, THREAD_SUSPEND_DISABLE }

thread_suspend_t

typedef enum thread_suspend_t thread_suspend_t

thread_suspend_t

RETSIGTYPE  ccxx_sigsuspend (int)

ccxx_sigsuspend

[static]

Thread*  getThread (void)

getThread

throw_t  getException (void)

getException

void  setException (throw_t mode)

setException

void  ccxx_sleep (timeout_t msec)

ccxx_sleep

void  ccxx_yield (void)

ccxx_yield

Conditional (class)

Conditional

A conditional variable sychcronization object for one to one and one to many signal and control events between processes. Conditional variables may wait for and receive signals to notify when to resume or perform operations. Multiple waiting threads may be woken with a broadcast signal.

Event (class)

Event

The Event class implements a feature originally found in the WIN32 API; event notification. A target thread waits on a resetable Event, and one or more other threads can then signal the waiting thread to resume execution. A timeout can be used to specify a wait duration in milliseconds. The Event class must be reset before it can be used again as a trigger. These event objects use a trigger/reset mechanism and are related to low level conditional variables.

Mutex (class)

Mutex

The Mutex class is used to protect a section of code so that at any given time only a single thread can perform the protected operation.

The Mutex can be used as a base class to protect access in a derived class. When used in this manner, the ENTER_CRITICAL and LEAVE_CRITICAL macros can be used to specify when code written for the derived class needs to be protected by the default Mutex of the derived class, and hence is presumed to be 'thread safe' from multiple instance execution. One of the most basic Common C++ synchronization object is the Mutex class. A Mutex only allows one thread to continue execution at a given time over a specific section of code. Mutex's have a enter and leave method; only one thread can continue from the Enter until the Leave is called. The next thread waiting can then get through. Mutex's are also known as "CRITICAL SECTIONS" in win32-speak.

The Mutex is always recursive in that if the same thread invokes the same mutex lock multiple times, it must release it multiple times. This allows a function to call another function which also happens to use the same mutex lock when called directly. This was deemed essential because a mutex might be used to block individual file requests in say, a database, but the same mutex might be needed to block a whole series of database updates that compose a "transaction" for one thread to complete together without having to write alternate non-locking member functions to invoke for each part of a transaction.

Strangely enough, the original pthread draft standard does not directly support recursive mutexes. In fact this is the most common "NP" extension for most pthread implementations. Common C++ emulates recursive mutex behavior when the target platform does not directly support it.

In addition to the Mutex, Common C++ supports a rwlock class. This implements the X/Open recommended "rwlock". On systems which do not support rwlock's, the behavior is emulated with a Mutex; however, the advantage of a rwlock over a mutex is then entirely lost. There has been some suggested clever hacks for "emulating" the behavior of a rwlock with a pair of mutexes and a semaphore, and one of these will be adapted for Common C++ in the future for platforms that do not support rwlock's directly.

MutexLock (class)

MutexLock

The MutexLock class is used to protect a section of code so that at any given time only a single thread can perform the protected operation.

It use Mutex to protect operation. Using this class is usefull and exception safe.

A common use is

void func_to_protect() { MutexLock lock(mutex); ... operation ... }

NOTE: do not declare variable as "MutexLock (mutex)", the mutex will be released at statement end.

ThreadLock (class)

ThreadLock

The ThreadLock class impliments a thread rwlock for optimal reader performance on systems which have rwlock support, and reverts to a simple mutex for those that do not.

MutexCounter (class)

MutexCounter

The Mutex Counter is a counter variable which can safely be incremented or decremented by multiple threads. A Mutex is used to protect access to the counter variable (an integer). An initial value can be specified for the counter, and it can be manipulated with the ++ and -- operators.

AtomicCounter (class)

AtomicCounter

The AtomicCounter class offers thread-safe manipulation of an integer counter. These are commonly used for building thread-safe "reference" counters for C++ classes. The AtomicCounter depends on the platforms support for "atomic" integer operations, and can alternately substitute a "mutex" if no atomic support exists.

Semaphore (class)

Semaphore

A semaphore is generally used as a synchronization object between multiple threads or to protect a limited and finite resource such as a memory or thread pool. The semaphore has a counter which only permits access by one or more threads when the value of the semaphore is non-zero. Each access reduces the current value of the semaphore by 1. One or more threads can wait on a semaphore until it is no longer 0, and hence the semaphore can be used as a simple thread synchronization object to enable one thread to pause others until the thread is ready or has provided data for them. Semaphores are typically used as a counter for protecting or limiting concurrent access to a given resource, such as to permitting at most "x" number of threads to use resource "y", for example.

Buffer (class)

Buffer

The buffer class represents an IPC service that is built upon a buffer of fixed capacity that can be used to transfer objects between one or more producer and consumer threads. Producer threads post objects into the buffer, and consumer threads wait for and receive objects from the buffer. Semaphores are used to to block the buffer from overflowing and indicate when there is data available, and mutexes are used to protect multiple consumers and producer threads from stepping over each other.

The buffer class is an abstract class in that the actual data being buffered is not directly specified within the buffer class itself. The buffer class should be used as a base class for a class that actually impliments buffering and which may be aware of the data types actually are being buffered. A template class could be created based on buffer for this purpose. Another possibility is to create a class derived from both Thread and Buffer which can be used to implement message passing threads.

FixedBuffer (class)

FixedBuffer

A buffer class that holds a known capacity of fixed sized objects defined during creation.

typedef int signo_t

signo_t

PosixThread (class)

PosixThread

ThreadKey (class)

ThreadKey

This class allows the creation of a thread context unique "pointer" that can be set and retrieved and can be used to create thread specific data areas for implementing "thread safe" library routines.

Finally, Common C++ supports a thread-safe "AtomicCounter" class. This can often be used for reference counting without having to protect the counter with a separate Mutex counter. This lends to lighter-weight code.

TimerPort (class)

TimerPort

Timer ports are used to provide synchronized timing events when managed under a "service thread" such as SocketService. This is made into a stand-alone base class since other derived libraries (such as the serial handlers) may also use the pooled "service thread" model and hence also require this code for managing timing.

inline int  get (Buffer &b, void *o)

get

inline int  put (Buffer &b, void *o)

put

inline int  peek (Buffer &b, void *o)

peek

struct timespec * gettimeout (struct timespec *spec, timeout_t timeout)

gettimeout

void  wait (signo_t signo)

wait

void  pdetach (void)

pdetach

This function provides a simple and portable means to fork/detach a process into a daemon.

Poller (class)

Poller

The poller class is used to help manage pollfd structs for use in the updated serial and socket "port" code.

typedef unsigned long pos_t

pos_t

typedef size_t ccxx_size_t

ccxx_size_t

typedef struct _fcb

_fcb

enum { FILE_OPEN_READONLY = O_RDONLY, FILE_OPEN_WRITEONLY = O_WRONLY, FILE_OPEN_READWRITE = O_RDWR, FILE_OPEN_APPEND = O_WRONLY | O_APPEND, FILE_OPEN_SYNC = O_RDWR, FILE_OPEN_TRUNCATE = O_RDWR | O_TRUNC }

enum fileattr_t { FILE_ATTR_INVALID = 0, FILE_ATTR_PRIVATE = 0400 | 0200, FILE_ATTR_GROUP = FILE_ATTR_PRIVATE | 0040 | 0020, FILE_ATTR_PUBLIC = FILE_ATTR_GROUP | 0004 | 0002 }

fileattr_t

typedef enum fileattr_t fileattr_t

fileattr_t

enum fileerror_t { FILE_SUCCESS = 0, FILE_NOT_OPENED, FILE_MAP_FAILED, FILE_INIT_FAILED, FILE_OPEN_DENIED, FILE_OPEN_FAILED, FILE_OPEN_INUSE, FILE_READ_INTERRUPTED, FILE_READ_INCOMPLETE, FILE_READ_FAILURE, FILE_WRITE_INTERRUPTED, FILE_WRITE_INCOMPLETE, FILE_WRITE_FAILURE, FILE_EXTENDED_ERROR }

fileerror_t

typedef enum fileerror_t fileerror_t

fileerror_t

enum fileaccess_t { FILE_ACCESS_READONLY = O_RDONLY, FILE_ACCESS_WRITEONLY= O_WRONLY, FILE_ACCESS_READWRITE = O_RDWR }

fileaccess_t

typedef enum fileaccess_t fileaccess_t

fileaccess_t

enum filecomplete_t { FILE_COMPLETION_IMMEDIATE, FILE_COMPLETION_DELAYED, FILE_COMPLETION_DEFERRED }

filecomplete_t

typedef enum filecomplete_t filecomplete_t

filecomplete_t

fifostream (class)

fifostream

This class provides a few alterations to the standard fstream class for dealing with fifo devices. In particular, a fifo is assumed to be created via mkfifo and is destroyed when closed. The fifo is a r/w streamable object. fifo streams are presumed unique to posix systems and are generally not portable classes.

FIFOSession (class)

FIFOSession

The FIFOSession produces a seperate thread which can manage a fifo stream session. This is somewhat similar to TTYSession and TCPSession in purpose.

Dir (class)

Dir

A low level portable directory class. Used to support ccstd Directory container. This provides a basic mechanism for allocating and accessing file entries.

RandomFile (class)

RandomFile

The purpose of this class is to define a base class for low level random file access that is portable between Win32 and Posix systems. This class is a foundation both for optimized thread shared and traditional locked file access that is commonly used to build database services, rather than the standard C++ streaming file classes.

ThreadFile (class)

ThreadFile

This class defines a database I/O file service that can be shared by multiple threads. All threads access a global copy of the database object, and mutex locks can be used to preserve transaction integrety. pread/pwrite calls can be used for optimized I/O when supported.

ThreadFile is meant for use by a threaded database server where multiple threads may each perform semi-independent operations on a given database table stored on disk. A special "fcb" structure is used to hold file "state", and pread/pwrite is used whenever possible for optimized I/O. On systems that do not offer pwread/pwrite, a Mutex lock is used to protect concurrent lseek and read/write operations. ThreadFile managed databases are assumed to be used only by the local server and through a single file descriptor.

SharedFile (class)

SharedFile

This class defines a database I/O file service that can be shared by multiple processes. Each thread should access a dup of the database object, and mutex locks can be used to preserve transaction integrety if multiple threads are used.

SharedFile is used when a database may be shared between multiple processes. SharedFile automatically applies low level byte-range "file locks", and provides an interface to fetch and release byte-range locked portions of a file.

MappedFile (class)

MappedFile

Create and map a disk file into memory. This portable class works under both Posix via mmap and under the win32 API. A mapped file can be referenced directly by it's memory segment. One can map and unmap portions of a file on demand, and update changed memory pages mapped from files immediately through sync().

Pipe (class)

Pipe

The Pipe uses system kernel buffering to hold data being passed either between two execution contexts within the same process, or between different processes. Unlike thread's "Buffer", Pipe uses system descriptors and kernel memory. Under Posix, the size of the pipe and associated kernel memory is always a fixed constant as defined by _PC_PIPE_BUF. The Common C++ "pipe" class primarily deals with "atomic" transfers of fixed sized objects through pipes. Pipes may pass data arbitrarily and can also be used through the "pipestream" class.

The "Pipe" class is not meant to be a true "public" class, but as a builder class for deriving other classes.

DSO (class)

DSO

The DSO dynamic loader class is used to load object files. On elf based systems this is typically done with dlopen. A dummy stub class is generated for non-dl capable systems.

bool  isDir (const char *path)

isDir

bool  isFile (const char *path)

isFile

bool  isDevice (const char *path)

isDevice

bool  canAccess (const char *path)

canAccess

bool  canModify (const char *path)

canModify

enum sockstate_t { SOCKET_INITIAL, SOCKET_AVAILABLE, SOCKET_BOUND, SOCKET_CONNECTED, SOCKET_CONNECTING, SOCKET_STREAM }

sockstate_t

used to enumerate type of socket I/O blocking - or non blocking

typedef enum sockstate_t sockstate_t

sockstate_t

enum sockerror_t { SOCKET_SUCCESS = 0, SOCKET_CREATE_FAILED, SOCKET_COPY_FAILED, SOCKET_INPUT_ERROR, SOCKET_INPUT_INTERRUPT, SOCKET_RESOURCE_FAILURE, SOCKET_OUTPUT_ERROR, SOCKET_OUTPUT_INTERRUPT, SOCKET_NOT_CONNECTED, SOCKET_CONNECT_REFUSED, SOCKET_CONNECT_REJECTED, SOCKET_CONNECT_TIMEOUT, SOCKET_CONNECT_FAILED, SOCKET_CONNECT_INVALID, SOCKET_CONNECT_BUSY, SOCKET_CONNECT_NOROUTE, SOCKET_BINDING_FAILED, SOCKET_BROADCAST_DENIED, SOCKET_ROUTING_DENIED, SOCKET_KEEPALIVE_DENIED, SOCKET_SERVICE_DENIED, SOCKET_SERVICE_UNAVAILABLE, SOCKET_MULTICAST_DISABLED, SOCKET_TIMEOUT_ERROR, SOCKET_NODELAY_ERROR, SOCKET_EXTENDED_ERROR }

sockerror_t

typedef enum sockerror_t sockerror_t

sockerror_t

enum socktos_t { SOCKET_IPTOS_LOWDELAY, SOCKET_IPTOS_THROUGHPUT, SOCKET_IPTOS_RELIABILITY, SOCKET_IPTOS_MINCOST, SOCKET_IPTOS_INVALID }

socktos_t

typedef enum socktos_t socktos_t

socktos_t

enum sockpend_t { SOCKET_PENDING_INPUT, SOCKET_PENDING_OUTPUT, SOCKET_PENDING_ERROR }

sockpend_t

typedef enum sockpend_t sockpend_t

sockpend_t

typedef unsigned short tpport_t

tpport_t

Transport Protocol Ports.

InetAddress (class)

InetAddress

The network name and address objects are all derived from a common InetAddress base class. Specific classes, such as InetHostAddress, InetMaskAddress, etc, are defined from InetAddress entirely so that the manner a network address is being used can easily be documented and understood from the code and to avoid common errors and accidental misuse of the wrong address object. For example, a "connection" to something that is declared as a "InetHostAddress" can be kept type-safe from a "connection" accidently being made to something that was declared a "InetBroadcastAddress".

InetHostAddress (class)

InetHostAddress

This object is used to hold the actual and valid internet address of a specific host machine that will be accessed through a socket.

InetMaskAddress (class)

InetMaskAddress

Internet addresses used specifically as masking addresses (such as " 255.255.255.0") are held in the InetMaskAddress derived object. The seperate class is used so that C++ type casting can automatically determine when an InetAddress object is really a mask address object rather than simply using the base class. This also allows manipulative operators for address masking to operate only when presented with a Masked address as well as providing cleaner and safer source.

BroadcastAddress (class)

BroadcastAddress

The broadcast address object is used to store the broadcast address for a specific subnet. This is commonly used for UDP broadcast operations.

Socket (class)

Socket

The Socket is used as the base for all Internet protocol services under Common C++. A socket is a system resource (or winsock descriptor) that occupies a specific port address (and may be bound to a specific network interface) on the local machine. The socket may also be directly connected to a specific socket on a remote internet host.

This base class is not directly used, but is provided to offer properties common to other Common C++ socket classes, including the socket exception model and the ability to set socket properties such as QoS, "sockopts" properties like Dont-Route and Keep-Alive, etc.

UDPSocket (class)

UDPSocket

UDP sockets implement the TCP SOCK_DGRAM UDP protocol. They can be used to pass unverified messages between hosts, or to broadcast a specific message to an entire subnet. Please note that Streaming of realtime data commonly use UDPDuplex related classes rather than UDPSocket.

In addition to connected TCP sessions, Common C++ supports UDP sockets and these also cover a range of functionality. Like a TCPSocket, A UDPSocket can be created bound to a specific network interface and/or port address, though this is not required. UDP sockets also are usually either connected or otherwise "associated" with a specific "peer" UDP socket. Since UDP sockets operate through discreet packets, there are no streaming operators used with UDP sockets.

In addition to the UDP "socket" class, there is a "UDPBroadcast" class. The UDPBroadcast is a socket that is set to send messages to a subnet as a whole rather than to an individual peer socket that it may be associated with.

UDP sockets are often used for building "realtime" media streaming protocols and full duplex messaging services. When used in this manner, typically a pair of UDP sockets are used together; one socket is used to send and the other to receive data with an associated pair of UDP sockets on a "peer" host. This concept is represented through the Common C++ UDPDuplex object, which is a pair of sockets that communicate with another UDPDuplex pair.

UDPBroadcast (class)

UDPBroadcast

Representing a UDP socket used for subnet broadcasts, this class provides an alternate binding and setPeer() capability for UDP sockets.

UDPTransmit (class)

UDPTransmit

Representing half of a two-way UDP connection, the UDP transmitter can broadcast data to another selected peer host or to an entire subnet.

UDPReceive (class)

UDPReceive

Representing half of a two-way UDP connection, the UDP receiver can receive data from another peer host or subnet. This class is used exclusivily to derive the UDPDuplex.

UDPDuplex (class)

UDPDuplex

UDP duplex connections impliment a bi-directional point-to-point UDP session between two peer hosts. Two UDP sockets are typically used on alternating port addresses to assure that sender and receiver data does not collide or echo back. A UDP Duplex is commonly used for full duplex real-time streaming of UDP data between hosts.

TCPSocket (class)

TCPSocket

TCP sockets are used for stream based connected sessions between two sockets. Both error recovery and flow control operate transparently for a TCP socket connection. The TCP socket base class is primary used to bind a TCP "server" for accepting TCP streams.

An implicit and unique TCPSocket object exists in Common C++ to represent a bound TCP socket acting as a "server" for receiving connection requests. This class is not part of TCPStream because such objects normally perform no physical I/O (read or write operations) other than to specify a listen backlog queue and perform "accept" operations for pending connections. The Common C++ TCPSocket offers a Peek method to examine where the next pending connection is coming from, and a Reject method to flush the next request from the queue without having to create a session.

The TCPSocket also supports a "OnAccept" method which can be called when a TCPStream related object is created from a TCPSocket. By creating a TCPStream from a TCPSocket, an accept operation automatically occurs, and the TCPSocket can then still reject the client connection through the return status of it's OnAccept method.

TCPStream (class)

TCPStream

TCP streams are used to represent TCP client connections to a server by TCP protocol servers for accepting client connections. The TCP stream is a C++ "stream" class, and can accept streaming of data to and from other C++ objects using the << and >> operators.

TCPStream itself can be formed either by connecting to a bound network address of a TCP server, or can be created when "accepting" a network connection from a TCP server.

tcpstream (class)

tcpstream

A more natural C++ "tcpstream" class for use by non-threaded applications. This class behaves a lot more like fstream and similar classes.

TCPSession (class)

TCPSession

The TCP session is used to primarily to represent a client connection that can be managed on a seperate thread. The TCP session also supports a non-blocking connection scheme which prevents blocking during the constructor and moving the process of completing a connection into the thread that executes for the session.

InetAddrValidator (class)

InetAddrValidator

Classes derived from InetAddress would require an specific validator to pass to the InetAddress constructor. This is a base class for classes of function objects used by such derived classes.

InetMcastAddrValidator (class)

InetMcastAddrValidator

Class for the function object that validates multicast addresses. Implements a specific application operator to validate multicast addresses.

InetMcastAddress (class)

InetMcastAddress

A specialization of InetAddress that provides address validation for multicast addresses. Whenever its value changes the new value is checked to be in the range from 224.0.0.1 through 239.255.255.255. If it is not, an exception is thrown.

extern std::ostream&  operator<< (std::ostream &os, const InetAddress &ia)

operator<<

inline struct in_addr  getaddress (const InetAddress &ia)

getaddress

SocketService (class)

SocketService

The SocketService is a thread pool object that is meant to service attached socket ports. Multiple pool objects may be created and multiple socket ports may be attached to the same thread of execution. This allows one to balance threads and sockets they service rather than either using a single thread for all connections or a seperate thread for each connection. Features can be added through supported virtual methods.

SocketPort (class)

SocketPort

The socket port is an internal class which is attached to and then serviced by a specific SocketService "object". Derived versions of this class offer specific functionality for specific protocols. Both Common C++ supporting frameworks and application objects may be derived from related protocol specific base classes.

A special set of classes, "SocketPort" and "SocketService", exist for building realtime streaming media servers on top of UDP and TCP protocols. The "SocketPort" is used to hold a connected or associated TCP or UDP socket which is being "streamed" and which offers callback methods that are invoked from a "SocketService" thread. SocketService's can be pooled into logical thread pools that can service a group of SocketPorts. A millisecond accurate "timer" is associated with each SocketPort and can be used to time synchronize SocketPort I/O operations.

enum sioerror_t { SERIAL_SUCCESS = 0, SERIAL_OPEN_NOTTY, SERIAL_OPEN_FAILED, SERIAL_SPEED_INVALID, SERIAL_FLOW_INVALID, SERIAL_PARITY_INVALID, SERIAL_CHARSIZE_INVALID, SERIAL_STOPBITS_INVALID, SERIAL_OPTION_INVALID, SERIAL_RESOURCE_FAILURE, SERIAL_OUTPUT_ERROR, SERIAL_INPUT_ERROR, SERIAL_TIMEOUT_ERROR, SERIAL_EXTENDED_ERROR }

sioerror_t

typedef enum sioerror_t sioerror_t

sioerror_t

enum sioflow_t { SERIAL_FLOW_NONE, SERIAL_FLOW_SOFT, SERIAL_FLOW_HARD, SERIAL_FLOW_BOTH }

sioflow_t

typedef enum sioflow_t sioflow_t

sioflow_t

enum sioparity_t { SERIAL_PARITY_NONE, SERIAL_PARITY_ODD, SERIAL_PARITY_EVEN }

sioparity_t

typedef enum sioparity_t sioparity_t

sioparity_t

enum siopend_t { SERIAL_PENDING_INPUT, SERIAL_PENDING_OUTPUT, SERIAL_PENDING_ERROR }

siopend_t

typedef enum siopend_t siopend_t

siopend_t

Serial (class)

Serial

The Serial class is used as the base for all serial I/O services under APE. A serial is a system serial port that is used either for line or packet based data input. Serial ports may also be "streamable" in a derived form.

Common C++ serial I/O classes are used to manage serial devices and implement serial device protocols. From the point of view of Common C++, serial devices are supported by the underlying Posix specified "termios" call interface.

The serial I/O base class is used to hold a descriptor to a serial device and to provide an exception handling interface for all serial I/O classes. The base class is also used to specify serial I/O properties such as communication speed, flow control, data size, and parity. The "Serial" base class is not itself directly used in application development, however.

Common C++ Serial I/O is itself divided into two conceptual modes; frame oriented and line oriented I/O. Both frame and line oriented I/O makes use of the ability of the underlying tty driver to buffer data and return "ready" status from when select either a specified number of bytes or newline record has been reached by manipulating termios c_cc fields appropriately. This provides some advantage in that a given thread servicing a serial port can block and wait rather than have to continually poll or read each and every byte as soon as it appears at the serial port.

TTYStream (class)

TTYStream

TTY streams are used to represent serial connections that are fully "streamable" objects using C++ stream classes and friends.

The first application relevant serial I/O class is the TTYStream class. TTYStream offers a linearly buffered "streaming" I/O session with the serial device. Furthermore, traditional C++ "stream" operators (<< and >>) may be used with the serial device. A more "true" to ANSI C++ library format "ttystream" is also available, and this supports an "open" method in which one can pass initial serial device parameters immediately following the device name in a single string, as in "/dev/tty3a:9600,7,e,1", as an example.

The TTYSession aggragates a TTYStream and a Common C++ Thread which is assumed to be the execution context that will be used to perform actual I/O operations. This class is very anagolous to TCPSession.

ttystream (class)

ttystream

A more natural C++ "ttystream" class for use by non-threaded applications. This class behaves a lot more like fstream and similar classes.

TTYSession (class)

TTYSession

The TTYSession aggragates a TTYStream and a Common C++ Thread which is assumed to be the execution context that will be used to perform actual I/O operations. This class is very anagolous to TCPSession.

SerialPort (class)

SerialPort

The serial port is an internal class which is attached to and then serviced by a specified SerialService thread. Derived versions of this class offer specific functionality such as serial integration protocols.

The TTYPort and TTYService classes are used to form thread-pool serviced serial I/O protocol sets. These can be used when one has a large number of serial devices to manage, and a single (or limited number of) thread(s) can then be used to service the tty port objects present. Each tty port supports a timer control and several virtual methods that the service thread can call when events occur. This model provides for "callback" event management, whereby the service thread performs a "callback" into the port object when events occur. Specific events supported include the expiration of a TTYPort timer, pending input data waiting to be read, and "sighup" connection breaks.

SerialService (class)

SerialService

The SerialService is a thead service object that is meant to service attached serial ports. Multiple pool objects may be created and multiple serial ports may be attached to the same thread of of execution. This allows one to balance threads and the serial ports they service.

The TTYPort and TTYService classes are used to form thread-pool serviced serial I/O protocol sets. These can be used when one has a large number of serial devices to manage, and a single (or limited number of) thread(s) can then be used to service the tty port objects present. Each tty port supports a timer control and several virtual methods that the service thread can call when events occur. This model provides for "callback" event management, whereby the service thread performs a "callback" into the port object when events occur. Specific events supported include the expiration of a TTYPort timer, pending input data waiting to be read, and "sighup" connection breaks.

enum slog_class_t { SLOG_SECURITY, SLOG_AUDIT, SLOG_DAEMON, SLOG_USER, SLOG_DEFAULT }

slog_class_t

typedef enum slog_class_t slog_class_t

slog_class_t

enum slog_level_t { SLOG_EMERGENCY = 1, SLOG_ALERT, SLOG_CRITICAL, SLOG_ERROR, SLOG_WARNING, SLOG_NOTICE, SLOG_INFO, SLOG_DEBUG }

slog_level_t

typedef enum slog_level_t slog_level_t

slog_level_t

Slog (class)

Slog

The slog class is used to stream messages to the system's logging facility (syslogd). A default slog object is used to avoid confusion with the native syslog facility and to imply a logical relationship to the C++ clog().

The key difference is that the slog object sends it's output to the system logging daemon (typically syslogd) rather than through stderr. slog can be streamed with the << operator just like clog; a default slog object is pre-initialized, and you stream character data to it.

The slog allows one to specify logging levels and other properties through the () operators. Hence, once can do:

 slog("mydaemon", SLOG_DAEMON, SLOG_EMERGENCY) << I just died << endl; 

or things like:

 slog("mydaemon", SLOG_DAEMON); 
 slog(SLOG_INFO) << "daemon initalized" << endl; 

The intent is to be as common-place and as convenient to use as the stderr based clog facility found in C++, and this is especially useful for C++ daemons.

The std::flush manipulator doesn't work. Either the std::endl or std::ends manipulators must be used to cause the output to be sent to the daemon.

When this class is used on a system that doesn't have the syslog headers (i.e. a non-posix win32 box), the output goes to the a file with the same name as the syslog identifier string with '.log' appended to it. If the identifier string ends in '.exe', the '.exe' is removed before the '.log' is appened. (e.g. the identifier foo.exe will generate a log file named foo.log)

extern Slog slog

slog

CommandOption (class)

CommandOption

CommandOption is the base class for all command line options. Command line options can be defined statically and used when constructing a command line parser onject using MakeCommandOptionParse. This serves only as a base class to CommandOptionWithArg, CommandOptionRest or CommandOptionNoArg which can also be used to derive more complex classes or even entire applications.

CommandOptionParse (class)

CommandOptionParse

This is the CommandOptionParse interface class. To implement this object you can call MakeCommandOptionParse(); This will instantiate a dynamically allocated version of this class and parse the command line for the list of command options that are passed in.

extern CommandOption * DefaultCommandOptionList

DefaultCommandOptionList

CommandOptionWithArg (class)

CommandOptionWithArg

Derived class of CommandOption for options that have a value associated with them. Classes CommandOptionRest and CommandOptionArg derive from this class.

CommandOptionArg (class)

CommandOptionArg

Class for options with an argument e.g. --option value .

CommandOptionRest (class)

CommandOptionRest

It only makes sense to have a single one of these set and it is exclusive with CommandOptionCollect. It is the option that takes the rest of the command line options that are not part of any other options. e.g. "strace -ofile command arg1 arg2". The "command arg1 arg2" part is placed in objects of this class.

CommandOptionCollect (class)

CommandOptionCollect

It only makes sense to have a single one of these set and it is also exclusive with CommandOptionRest. This makes parameter collecting behave line the Unix "cat" command.

CommandOptionNoArg (class)

CommandOptionNoArg

CommandOption type for flags.

CommandOptionParse *  MakeCommandOptionParse ( int argc, char ** argv, char * comment, CommandOption * options = DefaultCommandOptionList )

MakeCommandOptionParse

MakeCommandOptionParse will create an implementation of a CommandOptionParse object. This particular implementation is a wrapper around getopt_long(3). That interface unfortunatly does not provide enough information to give the best error messages with malformed input. If the implementation changes there is a good chance that the binary interface will remain the same.

typedef struct _keyval

_keyval

typedef struct _keysym

_keysym

typedef struct --

--

MemPager (class)

MemPager

The memory pager is used to allocate cumulative memory pages for storing object specific "persistant" data that is presumed to persist during the life of a given derived object. When the object is destroyed, all accumulated data is automatically purged.

There are a number of odd and specialized utility classes found in Common C++. The most common of these is the "MemPager" class. This is basically a class to enable page-grouped "cumulative" memory allocation; all accumulated allocations are dropped during the destructor. This class has found it's way in a lot of other utility classes in Common C++.

SharedMemPager (class)

SharedMemPager

The shared mempager uses a mutex to protect key access methods. This class is used when a mempager will be shared by multiple threads.

Keydata (class)

Keydata

Keydata objects are used to load and hold "configuration" data for a given application.

This class is used to load and then hold "keyword = value" pairs parsed from a text based "config" file that has been divided into "[sections]". The syntax is:

 [section_name]
 key1=value1
 key2=value2

Essentially, the "path" is a "keypath" into a theoretical namespace of key pairs, hence one does not use "real" filepaths that may be OS dependent. The "/" path refers to "/etc" prefixed (on UNIX) directories and this is processed within the constructor. It could refer to the /config prefix on QNX, or even, gasp, a "C:\WINDOWS". Hence, a keypath of "/bayonne.d/vmhost/smtp" actually resolves to a "/etc/bayonne.d/vmhost.conf" and loads key value pairs from the [smtp] section of that .conf file.

Similarly, something like "~bayonne/smtp" path refers to a "~/.bayonnerc" and loads key pairs from the [smtp] section. This coercion occurs before the name is passed to the open call.

I actually use derived keydata based classes as global initialized objects, and they hence automatically load and parse config file entries even before "main" has started.

Keydata can hold multiple values for the same key pair. This can occur either from storing a "list" of data items in a config file, or when overlaying multiple config sources (such as /etc/....conf and ~/.confrc segments) into a single object. The keys are stored as cumulative (read-only/replacable) config values under a hash index system for quick retrieval.

Keydata can also load a table of "initialization" values for keyword pairs that were not found in the external file.

One typically derives an application specific keydata class to load a specific portion of a known config file and initialize it's values. One can then declare a global instance of these objects and have configuration data initialized automatically as the executable is loaded.

Hence, if I have a "[paths]" section in a "/etc/server.conf?" file, I might define something like:

 class KeyPaths : public Keydata
 {
   public:
     KeyPaths() : Keydata("/server/paths")
     {
       static KEYDEF *defvalues = {
 	  {"datafiles", "/var/server"},
 	  {NULL, NULL}};

// override with [paths] from "~/.serverrc" if avail.

Load("~server/paths"); Load(defvalues); } };

KeyPaths keypaths;

StringTokenizer (class)

StringTokenizer

Splits delimited string into tokens.

The StringTokenizer takes a pointer to a string and a pointer to a string containing a number of possible delimiters. The StringTokenizer provides an input forward iterator which allows to iterate through all tokens. An iterator behaves like a logical pointer to the tokens, i.e. to shift to the next token, you've to increment the iterator, you get the token by dereferencing the iterator.

Memory consumption: This class operates on the original string and only allocates memory for the individual tokens actually requested, so this class allocates at maximum the space required for the longest token in the given string. Since for each iteration, memory is reclaimed for the last token, you MAY NOT store pointers to them; if you need them afterwards, copy them. You may not modify the original string while you operate on it with the StringTokenizer; the behaviour is undefined in that case.

The iterator has one special method 'nextDelimiter()' which returns a character containing the next delimiter following this tokenization process or '\0', if there are no following delimiters. In case of skipAllDelim, it returns the FIRST delimiter.

With the method 'setDelimiters(const char*)' you may change the set of delimiters. It affects all running iterators.

Example:

  StringTokenizer st("mary had a little lamb;its fleece was..", " ;");
  StringTokenizer::iterator i;
  for (i = st.begin() ; i != st.end() ; ++i) {
        cout << "Token: '" << *i << "'\t";
        cout << " next Delim: '" << i.nextDelimiter() << "'" << endl;
  }

PersistException (class)

PersistException

typedef class BaseObject*  (*NewBaseObjectFunction) (void)

(*NewBaseObjectFunction)

TypeManager (class)

TypeManager

This class manages the types for generation of the persistent objects. Its data structures are managed automatically by the system. They are implicitly filled by the constructors who declare classes to the system.

Engine (class)

Engine

Engine

This class constructs on a standard C++ STL stream and then operates in the mode specified.

BaseObject (class)

BaseObject

BaseObject

This object is the base for all Persistent data which is not natively serialised by the Persistence::Engine

It registers itself with the Persistence::TypeManager using a global constructor function. A matching deregister call is made in a global destructor, to allow DLL's to use the Persistence::Engine in a main executable.

Engine&  operator >> ( Engine& ar, BaseObject *&ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, BaseObject const *ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, int8& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, int8 ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, uint8& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, uint8 ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, int16& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, int16 ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, uint16& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, uint16 ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, int32& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, int32 ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, uint32& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, uint32 ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, int64& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, int64 ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, uint64& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, uint64 ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, float& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, float ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, double& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, double ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, std::string& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, std::string ob)
throw(Engine::Exception)

operator <<

Engine&  operator >> ( Engine& ar, bool& ob)
throw(Engine::Exception)

operator >>

Engine&  operator << ( Engine& ar, bool ob)
throw(Engine::Exception)

operator <<

template Engine&  operator << ( Engine& ar, std::vector const& ob)
throw(Engine::Exception)

operator <<

serialize a vector of some serializable content to the engine

template Engine&  operator >> ( Engine& ar, std::vector& ob)
throw(Engine::Exception)

operator >>

deserialize a vector of deserializable content from an engine.

template Engine&  operator << ( Engine& ar, std::map const & ob)
throw(Engine::Exception)

operator <<

serialize a map with keys/values which both are serializeable to an engine.

template Engine&  operator >> ( Engine& ar, std::map& ob)
throw(Engine::Exception)

operator >>

deserialize a map with keys/values which both are serializeable from an engine.

typedef enum --

--

Digest (class)

Digest

The digest base class is used for implementing and deriving one way hashing functions.

ChecksumDigest (class)

ChecksumDigest

A simple checksum digest function.

CRC16Digest (class)

CRC16Digest

A crc16 collection/compution hash accumulator class.

MD5Digest (class)

MD5Digest

A md5 collection/computation accululator class.

Number (class)

Number

A number manipulation class. This is used to extract, convert, and manage simple numbers that are represented in C ascii strings in a very quick and optimal way.

ZNumber (class)

ZNumber

Date (class)

Date

The Date class uses a julian date representation of the current year, month, and day. This is then manipulated in several forms and may be exported as needed.

DateNumber (class)

DateNumber

A number class that manipulates a string buffer that is also a date.

typedef unsigned long pos_t

pos_t

typedef size_t ccxx_size_t

ccxx_size_t

typedef struct _fcb

_fcb

enum { FILE_OPEN_READONLY = O_RDONLY, FILE_OPEN_WRITEONLY = O_WRONLY, FILE_OPEN_READWRITE = O_RDWR, FILE_OPEN_APPEND = O_WRONLY | O_APPEND, FILE_OPEN_SYNC = O_RDWR, FILE_OPEN_TRUNCATE = O_RDWR | O_TRUNC }

enum fileattr_t { FILE_ATTR_INVALID = 0, FILE_ATTR_PRIVATE = 0400 | 0200, FILE_ATTR_GROUP = FILE_ATTR_PRIVATE | 0040 | 0020, FILE_ATTR_PUBLIC = FILE_ATTR_GROUP | 0004 | 0002 }

fileattr_t

typedef enum fileattr_t fileattr_t

fileattr_t

enum fileerror_t { FILE_SUCCESS = 0, FILE_NOT_OPENED, FILE_MAP_FAILED, FILE_INIT_FAILED, FILE_OPEN_DENIED, FILE_OPEN_FAILED, FILE_OPEN_INUSE, FILE_READ_INTERRUPTED, FILE_READ_INCOMPLETE, FILE_READ_FAILURE, FILE_WRITE_INTERRUPTED, FILE_WRITE_INCOMPLETE, FILE_WRITE_FAILURE, FILE_EXTENDED_ERROR }

fileerror_t

typedef enum fileerror_t fileerror_t

fileerror_t

enum fileaccess_t { FILE_ACCESS_READONLY = O_RDONLY, FILE_ACCESS_WRITEONLY= O_WRONLY, FILE_ACCESS_READWRITE = O_RDWR }

fileaccess_t

typedef enum fileaccess_t fileaccess_t

fileaccess_t

enum filecomplete_t { FILE_COMPLETION_IMMEDIATE, FILE_COMPLETION_DELAYED, FILE_COMPLETION_DEFERRED }

filecomplete_t

typedef enum filecomplete_t filecomplete_t

filecomplete_t

bool  isDir (const char *path)

isDir

bool  isFile (const char *path)

isFile

bool  isDevice (const char *path)

isDevice

bool  canAccess (const char *path)

canAccess

bool  canModify (const char *path)

canModify

XMLStream (class)

XMLStream

This class impliments a basic XML stream parser that can be used to examine an XML resource thru virtual I/O methods. This class must be derived into one that can impliment the physical I/O required to parse actual data. A mixer class using XMLStream and URLStream would seem a likely combination for this purpose.

PluginGroup (class)

PluginGroup

A plugin group is used to manage a chain of associated plugins.

TimedGroup (class)

TimedGroup

A timed group is a scheduled entity that involves things that must be processed on some kind of interval.

ThreadGroup (class)

ThreadGroup

A thread grouping class for a set of server classes that may be started and stopped together as a common group.


Generated by: dyfet on home on Wed Dec 5 07:05:45 2001, using kdoc 2.0a53.