libcprops

Section: libcprops overview (3)
Updated: OCTOBER 2005
Index Return to Main Contents

NAME

cprops - the c prototyping tools library

DESCRIPTION

the cprops library consists of implementations for several widely used data structures, logging facilities, threading and load balancing as well as rudimentary tcp/httpd functionality.

the public types and functions defined by cprops are prefixed with 'cp_' to allow usage with other libraries that might implement similar types. Other functions are for internal use and may not be supported in future releases.

Here's a list of goodies.

data structures

cp_string

a 'safe string' implementation

cp_vector

a 'safe array' implementation

cp_list

a doubly linked list implementation

cp_priority_list

a 'priority list' implementation featuring an optional 'immediate' and any number of 'normal' priority queues. Queue weights are assigned on creation. The extraction algorithm is a weight based round robin with override priority for the 'immediate' queue if one is defined.

cp_hashtable

a hashtable implementation

cp_hashlist

a hashtable supporting insertion order conservation and quick iteration.

cp_avltree

an AVL tree implementation. AVL trees are height balanced binary trees with a guaranteed lookup time of O(log n). Advantages over hashtables are that hashtables require a hash function, do not maintain iteration order (although hashlists do) and have a worst case lookup time of O(n).

cp_rbtree

a red-black tree implementation. Red black trees are height balanced binary trees simillar in performance to AVL trees. On average, insertion and deletion operations are faster than in AVL trees, whereas lookups may be somewhat slower.

cp_splaytree

a splay tree implementation. In splay trees, every tree operation (insert, delete, lookup) brings the affected node to the root of the tree. This makes splay trees useful for applications where the search space is much larger than the group of mappings most frequently accessed. A drawback in applications where the tree can be accessed from multiple threads is that since the lookup operation changes the tree structure, the tree must be write- locked during lookup. In other collection implementations lookup requires a read-lock only, allowing simultaneous access from multiple readers.

cp_trie

a character trie implementation which can be used for string prefix matching, and is used internally in the http service implementation for routing requests to services by uri.

insertion, extraction an removal operations on collection types are synchronized by default. This behavior can be controlled by creating instances using the *_by_mode constructor versions with COLLECTION_MODE_NOSYNC, or by calling the *_by_mode api functions.

general purpose tools

cp_thread_pool

a thread pool implementation. Threads are created on pool initialization and exit on pool destruction. When client code exits the thread returns to the pool to wait for the next request. This eliminates the thread creation time overhead.

cp_pooled_thread_scheduler

a load balancer for cp_thread_pool clients. The pooled cp_thread scheduler interface is meant for use by clients who require a variable number of cp_threads. Each such component may create an instance of cp_pooled_thread_client_interface and use the api functions to get cp_threads from the underlying cp_thread_pool. Load balancing is managed distributedly, based on load factors reported by scheduler clients.

cp_client

a tcp client socket. Create a cp_client with a host string and a port, for ssl connections specify a certificate authority certificate file or directory.

cp_socket

a tcp 'server socket' implementation. Create a cp_socket to listen on a port, specify a callback to implemet your communication protocol (libcprops provides a basic http implementation you could plug in) and the strategy you want for handling multiple connections - use a thread pool to serve each connection on its own thread or specify a callback to process requests by a single thread as they are read in a more select()-like approach.

cp_httpclient

an http client implementation. cp_httpclient objects are created to retrieve content from a specific host and port. The same object may be reused for the same uri or other uris. cp_httpclient supports ssl, proxies, cookies, and redirects and offers synchronous, asynchronous and multi-threaded interfaces.

cp_httpsocket

a partial http implementation. Based on cp_socket. Instantiate a cp_httpsocket to listen on a port, register cp_http_services per uri, receive an cp_http_request and fill up a cp_http_response structure to respond to requests.

dbms abstraction layer - cp_dbms

cprops provides a dbms abstraction layer, allowing performing dbms operations through a unified api independent of the actual implementation. Currently postgres and mysql are supported. Switching between datbases is nearly transparent - the only difference is the database specific call to create a connection factory.

logging

cprops provides simple logging facilities.

DEPENDENCIES

libcprops uses the pthread and POSIX regex libraries.

COMPILING AND LINKING

compiling and linking require the same command line syntax required to link with the pthread library.

on linux, compile with -D_REENTRANT -D_XOPEN_SOURCE=500. Link with -lpthread -lcprops.