initial commit.0.0

8 files changed, 716 insertions, 0 deletions

diff --git a/include/.gitignore b/include/.gitignore
new file mode 100644
index 0000000..3dda729
--- a/dev/null
+++ b/include/.gitignore
@@ -0,0 +1,2 @@
+Makefile.in
+Makefile
diff --git a/include/Makefile.am b/include/Makefile.am
new file mode 100644
index 0000000..3e043d3
--- a/dev/null
+++ b/include/Makefile.am
@@ -0,0 +1,12 @@
+EXTRA_DIST = konforka/pqxx_pile.h
+EXTRA_HEADERS=
+if HAVE_PQXX
+EXTRA_HEADERS += konforka/pqxx_pile.h
+endif
+
+nobase_include_HEADERS = \
+	konforka/exception.h \
+	konforka/basic_wrapper.h konforka/responsible_wrapper.h \
+	konforka/resource_pile.h \
+	konforka/pointer_map.h \
+	${EXTRA_HEADERS}
diff --git a/include/konforka/basic_wrapper.h b/include/konforka/basic_wrapper.h
new file mode 100644
index 0000000..909f8b6
--- a/dev/null
+++ b/include/konforka/basic_wrapper.h
@@ -0,0 +1,118 @@
+#ifndef __KONFORKA_BASIC_WRAPPER_H
+#define __KONFORKA_BASIC_WRAPPER_H
+
+/**
+ * @file
+ * @brief The konforka::basic_wrapper class declaration.
+ */
+
+#include <konforka/exception.h>
+
+namespace konforka {
+
+    /**
+     * @brief The basic wrapper class.
+     *
+     */
+    template<typename T>
+	class basic_wrapper {
+	    public:
+		/**
+		 * The type of wrapped content.
+		 */
+		typedef T content_type;
+
+		/**
+		 * The content wrapped into the instance.
+		 */
+		content_type opkele;
+		/**
+		 * This boolean indicates whether the object has a content
+		 * attached to it.
+		 */
+		bool bopkele;
+
+		/**
+		 * Default constructors creates the object with no content
+		 * associated with it.
+		 */
+		basic_wrapper()
+		    : bopkele(false) { }
+		/**
+		 * The constructor associates the content give with the object.
+		 * @param o the content being attached to the object.
+		 */
+		basic_wrapper(content_type o)
+		    : opkele(o), bopkele(true) { }
+		/**
+		 * Virtual destructor doing nothing in this class.
+		 */
+		virtual ~basic_wrapper() { }
+
+		/**
+		 * Attaches the given content to the object.
+		 * @param o the content being attached to the object.
+		 */
+		void attach(content_type o) {
+		    opkele = o;
+		    bopkele = true;
+		}
+
+		/**
+		 * Test whether the object has content attached.
+		 * @return naturally, returns true if yes.
+		 */
+		bool is() const {
+		    return bopkele;
+		}
+
+		/**
+		 * Throws an exception in case the object lacks content
+		 * attached.
+		 */
+		void ensure() const {
+		    if(!is())
+			throw konforka::exception(CODEPOINT,"no content attached");
+		}
+
+		/**
+		 * Get the content attached to the object. It would throw an
+		 * exception if there is no content attached.
+		 * @return reference to the content.
+		 */
+		virtual content_type& get_content() {
+		    ensure();
+		    return opkele;
+		}
+		/**
+		 * Get the content attached to the object. It would throw an
+		 * exception if there is no content attached.
+		 * @return const reference to the content.
+		 */
+		virtual const content_type& get_content() const {
+		    ensure();
+		    return opkele;
+		}
+
+		/**
+		 * Casts the object to the reference to the content type,
+		 * throwing an exception if there's no content associated with
+		 * an object.
+		 * @return reference to the content attached.
+		 * @see get_content()
+		 */
+		operator const content_type&(void) const { return get_content(); }
+		/**
+		 * Casts the object to the const reference to the content type,
+		 * throwing an exception if there's no content associated with
+		 * an object.
+		 * @return reference to the content attached.
+		 * @see get_content()
+		 */
+		operator content_type&(void) { return get_content(); }
+	};
+
+}
+
+#endif /* __KONFORKA_BASIC_WRAPPER_H */
+/* vim:set ft=cpp: */
diff --git a/include/konforka/exception.h b/include/konforka/exception.h
new file mode 100644
index 0000000..5e0bf96
--- a/dev/null
+++ b/include/konforka/exception.h
@@ -0,0 +1,203 @@
+#ifndef __KONFORKA_EXCEPTION_H
+#define __KONFORKA_EXCEPTION_H
+
+#include <exception>
+#include <string>
+#include <list>
+
+/**
+ * @file
+ * @brief exception-related stuff.
+ *
+ * Basic exception-related declarations and definitions.
+ */
+
+/**
+ * @def CODEPOINT
+ * the convenience definition of the parameters passed to the
+ * konforka::code_point constructor.
+ */
+#define	CODEPOINT __FILE__,__PRETTY_FUNCTION__,__LINE__
+/**
+ * @def NOCODEPOINT
+ * the convenience definition for the codepoint denoting no particular point in
+ * code.
+ */
+#define NOCODEPOINT "no information"
+
+/**
+ * @brief The main konforka namespace.
+ */
+namespace konforka {
+    using std::string;
+    using std::list;
+
+    /**
+     * @brief Pinpoint the code context.
+     *
+     * Class, holding the point in code, for instance, where the exception
+     * occured.
+     */
+    class code_point {
+	public:
+	    /**
+	     * The string describing the point in code.
+	     */
+	    string where;
+	    /**
+	     * The file (as provided by __FILE__) if available.
+	     */
+	    string file;
+	    /**
+	     * The function name (as provided by __PRETTY_FUNCTION__) if
+	     * available.
+	     */
+	    string function;
+	    /**
+	     * The line number (as provided by __LINE__) if available.
+	     */
+	    int line;
+
+	    /**
+	     * Constructs the object, using only textual description of the
+	     * point in code (no file, function, line information).
+	     * @param w the description of the point in code.
+	     */
+	    code_point(const string& w);
+	    /**
+	     * Constructs the object, specifying the exact position in code.
+	     * @param fi source file name.
+	     * @param fu function name.
+	     * @param l the line number.
+	     */
+	    code_point(const string& fi,const string& fu,int l);
+
+	    /**
+	     * Extract the information on the point in code.
+	     * @return the reference to the character string.
+	     * @see where
+	     */
+	    const char *c_str() const throw();
+
+	    /**
+	     * Build the textual description from the broken down information on
+	     * the point in code.
+	     * @see where
+	     * @see file
+	     * @see function
+	     * @see line
+	     */
+	    void make_where();
+    };
+
+    /**
+     * @brief The basic exception class.
+     */
+    class exception : public std::exception {
+	public:
+	    /**
+	     * The string, containing the description of exception.
+	     */
+	    string _what;
+	    /**
+	     * Reference to the point in code where the exception has occured.
+	     */
+	    code_point _where;
+	    /**
+	     * In case the exception has been rethrown a number of times, here
+	     * we can trace where was it seen (a kind of backtrace).
+	     */
+	    list<code_point> _seen;
+
+	    /**
+	     * The simple constructor, only providing textual information on the
+	     * exception nature and the point in code where the exception has
+	     * occured.
+	     * @param whe the point in code.
+	     * @param wha the description of exception.
+	     */
+	    exception(const string& whe, const string& wha);
+	    /**
+	     * The constructor, storing elaborate information on where the
+	     * exception has occured.
+	     * @param fi source file name.
+	     * @param fu function name.
+	     * @param l line number.
+	     * @param w the error message.
+	     * @see #CODEPOINT
+	     */
+	    exception(const string& fi,const string& fu,int l,const string& w);
+	    virtual ~exception() throw();
+
+	    /**
+	     * Extract the textual information on the point in code where
+	     * exception has occured.
+	     * @return the string describing point in code where exception has
+	     * occured.
+	     */
+	    virtual const char* where() const throw();
+	    /**
+	     * Extract the textual information on the nature of the exception.
+	     * @return the error message.
+	     */
+	    virtual const char* what() const throw();
+
+	    /**
+	     * Register the point in code (described by the string) in the
+	     * 'backtrace' list.
+	     * @param w the description of the point in code.
+	     */
+	    void see(const string& w);
+	    /**
+	     * Register the point in code in the 'backtrace' list.
+	     * @param fi souce file name.
+	     * @param fu function name.
+	     * @param l line number.
+	     * @see CODEPOINT
+	     */
+	    void see(const string& fi,const string& fu,int l);
+    };
+
+    /**
+     * @brief errno-holding exception.
+     *
+     * The exception object storing the information provided by the errno
+     * variable.
+     */
+    class system_error : public exception {
+	public:
+	    /**
+	     * The value of errno.
+	     */
+	    int _errno;
+
+	    /**
+	     * Construct the exception object storing plain text information on
+	     * the point in code.
+	     * @param whe the description of point in code.
+	     * @param wha the error message.
+	     */
+	    system_error(const string& whe,const string& wha);
+	    /**
+	     * Construct the exception object storing elaborate information on
+	     * the point in code where it has occured.
+	     * @param fi source file name.
+	     * @param fu function name.
+	     * @param l line number.
+	     * @param w the error message.
+	     * @see CODEPOINT
+	     */
+	    system_error(const string& fi,const string& fu,int l,const string& w);
+	    virtual ~system_error() throw();
+
+	    /**
+	     * Return the information on the system error recorded.
+	     * @return the string describing the error occured.
+	     */
+	    virtual const char* why() const throw();
+    };
+
+}
+
+#endif /* __KONFORKA_EXCEPTION_H */
+/* vim:set ft=cpp: */
diff --git a/include/konforka/pointer_map.h b/include/konforka/pointer_map.h
new file mode 100644
index 0000000..d706e71
--- a/dev/null
+++ b/include/konforka/pointer_map.h
@@ -0,0 +1,105 @@
+#ifndef __KONFORKA_POINTER_MAP_H
+#define __KONFORKA_POINTER_MAP_H
+
+#include <typeinfo>
+
+/**
+ * @file
+ * @brief mapping of pointers.
+ *
+ * The support for global mapping of pointers. Useful when using third-party
+ * libraries callbacks when the library does not provide mechanism for passing
+ * along custom context-dependent data.
+ */
+
+namespace konforka {
+
+    /**
+     * @brief internally used actual implementation of mapping pointer.
+     *
+     * @param tf the typeid of the key pointer.
+     * @param pf the key pointer.
+     * @param tt the typeid of the value pointer.
+     * @param pt the value pointer.
+     */
+    void _map_pointer(const type_info& tf,void *pf,const type_info& tt,void *pt);
+    /**
+     * @brief internally used actual implementation of destroying mapped
+     * pointer.
+     *
+     * @param tf the typeid of the key pointer.
+     * @param pf the key pointer.
+     * @param tt the typeid of the value pointer.
+     * @param pt the value pointer.
+     */
+    void _unmap_pointer(const type_info& tf,void *pf,const type_info& tt,void *pt);
+    /**
+     * @brief internally used actual implementation of retrieving mapped
+     * pointer.
+     *
+     * @param tf the typeid of the key pointer.
+     * @param pf the key pointer.
+     * @param tt the typeid of the value pointer.
+     * @return the value.
+     */
+    void *_mapped_pointer(const type_info& tf,void *pf,const type_info& tt);
+
+    /**
+     * @brief the object, maintaining mapped pointer.
+     * 
+     * @param from_t the key type.
+     * @param to_t the value type.
+     */
+    template<typename from_t,typename to_t>
+	class map_pointer {
+	    public:
+		/**
+		 * stored key.
+		 */
+		from_t _from;
+		/**
+		 * stored value.
+		 */
+		to_t _to;
+		/**
+		 * flag, specifying that the object is currently mapped.
+		 */
+		bool bmapped;
+
+		/**
+		 * @brief constructs the object, mapping the key/value pair.
+		 * 
+		 * @param f the key.
+		 * @param t the value.
+		 */
+		map_pointer(from_t f,to_t t)
+		    : _from(f), _to(t), bmapped(false) {
+			_map_pointer(typeid(from_t),_from,typeid(to_t),_to);
+			bmapped=true;
+		    }
+		/**
+		 * @brief destructor unmaps the key/value pair stored.
+		 */
+		~map_pointer() {
+		    if(bmapped)
+			_unmap_pointer(typeid(from_t),_from,typeid(to_t),_to);
+		}
+	};
+
+    /**
+     * The template function for pointer retrieval.
+     *
+     * @param from_t the key type.
+     * @param to_t the value type.
+     * @param f the key.
+     * @return the value.
+     */
+    template<typename from_t,typename to_t>
+	to_t mapped_pointer(from_t f) {
+	    return (to_t)_mapped_pointer(typeid(from_t),f,typeid(to_t));
+	}
+
+}
+
+#endif /* __KONFORKA_POINTER_MAP_H */
+/* vim:set ft=cpp: */
diff --git a/include/konforka/pqxx_pile.h b/include/konforka/pqxx_pile.h
new file mode 100644
index 0000000..fdfaed6
--- a/dev/null
+++ b/include/konforka/pqxx_pile.h
@@ -0,0 +1,59 @@
+#ifndef __KONFORKA_PQXX_PILE_H
+#define __KONFORKA_PQXX_PILE_H
+
+#include <pqxx/connection>
+#include <konforka/resource_pile.h>
+
+/**
+ * @file
+ * @brief libpqxx-based postgresql connections pile.
+ */
+
+namespace konforka {
+
+    /**
+     * @brief the base for pqxx-based connection classes.
+     *
+     * @param pqxxc_t the type of libpqxx connection (pqxx::connection,
+     * pqxx::lazyconnection or pqxx::asyncconnection).
+     */
+    template<typename pqxxc_t>
+	class pqxx_piled_connection_base : public resource_pile_base<string,pqxxc_t*, resource_pile_generic_ptr_factory<string,pqxxc_t> > {
+	    public:
+		/**
+		 * @brief the constractor based on connection info.
+		 *
+		 * @param ci connection info string.
+		 */
+		pqxx_piled_connection_base(const string& ci)
+		    : resource_pile_base<string,pqxxc_t*, resource_pile_generic_ptr_factory<string,pqxxc_t> >(ci) { }
+		~pqxx_piled_connection_base() { this->drop(); }
+
+		/**
+		 * @brief cast the object to the reference to the corresponding
+		 * libpqxx type.
+		 */
+		operator pqxxc_t&(void) { return *this->get_content(); }
+		/**
+		 * @brief cast the object to the const reference to the
+		 * corresponding libpqxx type.
+		 */
+		operator const pqxxc_t&(void) const { return *this->get_content(); }
+	};
+
+    /**
+     * @brief the implementation for piling pqxx::connection objects.
+     */
+    typedef pqxx_piled_connection_base<pqxx::connection> pqxx_piled_connection;
+    /**
+     * @brief the implementation for piling pqxx::lazyconnection objects.
+     */
+    typedef pqxx_piled_connection_base<pqxx::lazyconnection> pqxx_piled_lazy_connection;
+    /**
+     * @brief the implementation for piling pqxx::asyncconnection objects.
+     */
+    typedef pqxx_piled_connection_base<pqxx::asyncconnection> pqxx_piled_async_connection;
+}
+
+#endif /* __KONFORKA_PQXX_PILE_H */
+/* vim:set ft=cpp: */
diff --git a/include/konforka/resource_pile.h b/include/konforka/resource_pile.h
new file mode 100644
index 0000000..d76a07b
--- a/dev/null
+++ b/include/konforka/resource_pile.h
@@ -0,0 +1,118 @@
+#ifndef __KONFORKA_RESOURCE_PILE_H
+#define __KONFORKA_RESOURCE_PILE_H
+
+#include <map>
+#include <konforka/responsible_wrapper.h>
+
+/**
+ * @file
+ * @brief resource-piling base support.
+ *
+ * Base for implementing resource-piling.
+ */
+
+namespace konforka {
+    using std::multimap;
+    using std::pair;
+
+    /**
+     * @brief template base class for resource piling.
+     *
+     * @param key_t the type used for keying resources.
+     * @param value_t the type of resource itself.
+     * @param factory_t the factory class, providing value_t allocate(key_t)
+     * static member.
+     */
+    template<typename key_t,typename value_t,typename factory_t>
+	class resource_pile_base : public responsible_wrapper<value_t> {
+	    /**
+	     * @brief the type of the pile container itself.
+	     */
+	    typedef multimap<key_t,value_t> pile_t;
+	    /*
+	     * @brief the pile of resources.
+	     */
+	    static pile_t pile;
+	    public:
+	    /**
+	     * @brief stored value for the key associated with the resource
+	     * contained.
+	     */
+	    key_t _key;
+
+	    /**
+	     * @brief default constructor fetches or allocates resource.
+	     *
+	     * @param k the key for resource.
+	     * @see allocate
+	     */
+	    resource_pile_base(const key_t& k) {
+		allocate(k);
+	    }
+	    /**
+	     * @brief destructor releases the resource back to pile.
+	     */
+	    virtual ~resource_pile_base() { this->drop(); }
+
+	    /**
+	     * @brief this is where the resource is handed back to pile.
+	     */
+	    void release() {
+		pile.insert(pair<key_t,value_t>(_key,this->opkele));
+	    }
+
+	    /**
+	     * @brief fetch from pile or allocate the resource.
+	     *
+	     * Try to see if we have a piled resource keyed to the argument. If
+	     * we do -- fetch it from the pile, otherwise allocate anew.
+	     *
+	     * @param k the key for resource.
+	     */
+	    void allocate(const key_t& k) {
+		this->drop();
+		typename pile_t::iterator i = pile.find(k);
+		if(i==pile.end()) {
+		    this->attach(factory_t::allocate(k));
+		}else{
+		    this->attach(i->second);
+		    try{ pile.erase(i); }catch(...){ _key = k; throw; }
+		}
+		_key = k;
+	    }
+
+	};
+
+    template<typename key_t,typename value_t,typename factory_t>
+	typename resource_pile_base<key_t,value_t,factory_t>::pile_t
+	    resource_pile_base<key_t,value_t,factory_t>::pile;
+
+    /**
+     * @brief the generic single parameter new-based resource factory.
+     *
+     * The generic resource factory using new as a way to allocate resource
+     * using the single-parameter constructor.
+     *
+     * @param key_t the key type.
+     * @param value_t the resource type.
+     *
+     * @see resource_pile_base
+     */
+    template<typename key_t,typename value_t>
+	struct resource_pile_generic_ptr_factory {
+	    public:
+		/**
+		 * @brief allocate the resource using new.
+		 *
+		 * @param k the key.
+		 * @return pointer to the newly allocated object.
+		 */
+		static value_t *allocate(const key_t& k) {
+		    return new value_t(k);
+		}
+	};
+
+}
+
+#endif /* __KONFORKA_RESOURCE_PILE_H */
+/* vim:set ft=cpp: */
diff --git a/include/konforka/responsible_wrapper.h b/include/konforka/responsible_wrapper.h
new file mode 100644
index 0000000..374ad45
--- a/dev/null
+++ b/include/konforka/responsible_wrapper.h
@@ -0,0 +1,99 @@
+#ifndef __KONFORKA_RESPONSIBLE_WRAPPER_H
+#define __KONFORKA_RESPONSIBLE_WRAPPER_H
+
+/**
+ * @file
+ * @brief The konforka::responsible_wrapper class declaration.
+ */
+
+#include <konforka/basic_wrapper.h>
+
+namespace konforka {
+
+    /**
+     * @brief The auto-cleanup wrapper class.
+     *
+     * The wrapper class that may feel responsible for releasing the resources
+     * associated with the content attached.
+     *
+     */
+    template<typename T>
+	class responsible_wrapper : public basic_wrapper<T> {
+	    public:
+		/**
+		 * The type of wrapped content.
+		 */
+		typedef typename basic_wrapper<T>::content_type content_type;
+		/**
+		 * Flag indicating whether the object feels responsible for
+		 * releasing resources associated with the content.
+		 */
+		bool bresponsible;
+
+		/**
+		 * Default constructor creates the object with no content
+		 * attached.
+		 */
+		responsible_wrapper()
+		    : basic_wrapper<content_type>() { }
+		/**
+		 * Constructor, associating the content with the instance.
+		 * @param o the content.
+		 * @param br indicates whether resources associated with the
+		 * content should be released.
+		 */
+		responsible_wrapper(content_type o,bool br=true)
+		    : basic_wrapper<content_type>(o), bresponsible(br) { }
+		/**
+		 * Destructor releases resources associated with the content
+		 * attached (if any), if the instance feels responsible for the
+		 * content.
+		 */
+		virtual ~responsible_wrapper() { drop(); }
+
+		/**
+		 * Attaches the given content to the object.
+		 * @param o the content.
+		 * @param br indicates whether the object should feel
+		 * responsible for releasing the content.
+		 */
+		void attach(content_type o,bool br=true) {
+		    drop();
+		    basic_wrapper<content_type>::attach(o);
+		    bresponsible = true;
+		}
+
+		/**
+		 * 'empties' object, releasing resources associated with the
+		 * content if it feels responsible.
+		 */
+		virtual void drop() {
+		    if(!this->is())
+			return;
+		    if(bresponsible)
+			release();
+		    this->bopkele = false;
+		}
+
+		/**
+		 * Detaches the content from the object without releasing
+		 * resources even if feels responsible for it.
+		 * @return the content attached.
+		 */
+		virtual content_type detach() {
+		    this->ensure();
+		    this->bopkele = false;
+		    return this->opkele;
+		}
+
+		/**
+		 * Pure virtual provided for derived classes to override for
+		 * doing whatever it takes to release resources associated with
+		 * the content.
+		 */
+		virtual void release() = 0;
+	};
+}
+
+#endif /* __KONFORKA_RESPONSIBLE_WRAPPER_H */
+/* vim:set ft=cpp: */