diff options
| -rw-r--r-- | libadhocutil/Doxyfile | 328 | ||||
| -rw-r--r-- | libadhocutil/buffer.cpp | 6 | ||||
| -rw-r--r-- | libadhocutil/buffer.h | 48 | ||||
| -rw-r--r-- | libadhocutil/cache.h | 27 | ||||
| -rw-r--r-- | libadhocutil/cache.impl.h | 2 | ||||
| -rw-r--r-- | libadhocutil/curlHandle.h | 22 | ||||
| -rw-r--r-- | libadhocutil/curlMultiHandle.h | 11 | ||||
| -rw-r--r-- | libadhocutil/curlStream.h | 3 | ||||
| -rw-r--r-- | libadhocutil/intrusivePtrBase.h | 3 | ||||
| -rw-r--r-- | libadhocutil/lazyPointer.h | 17 | ||||
| -rw-r--r-- | libadhocutil/lockHelpers.h | 2 | ||||
| -rw-r--r-- | libadhocutil/nvpParse.h | 16 | ||||
| -rw-r--r-- | libadhocutil/processPipes.h | 25 | ||||
| -rw-r--r-- | libadhocutil/runtimeContext.h | 14 | ||||
| -rw-r--r-- | libadhocutil/scopeExit.h | 11 |
15 files changed, 512 insertions, 23 deletions
diff --git a/libadhocutil/Doxyfile b/libadhocutil/Doxyfile new file mode 100644 index 0000000..a95dcca --- /dev/null +++ b/libadhocutil/Doxyfile @@ -0,0 +1,328 @@ +# Doxyfile 1.8.10 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = libadhocutil +PROJECT_NUMBER = 0.1 +PROJECT_BRIEF = "Ad-hoc collection of utility classes and functions." +PROJECT_LOGO = +OUTPUT_DIRECTORY = bin +CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 4 +ALIASES = +TCL_SUBST = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES +AUTOLINK_SUPPORT = YES +BUILTIN_STL_SUPPORT = NO +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +IDL_PROPERTY_SUPPORT = YES +DISTRIBUTE_GROUP_DOC = NO +GROUP_NESTED_COMPOUNDS = NO +SUBGROUPING = YES +INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO +TYPEDEF_HIDES_STRUCT = NO +LOOKUP_CACHE_SIZE = 0 +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_PACKAGE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +HIDE_COMPOUND_REFERENCE= NO +SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO +FORCE_LOCAL_INCLUDES = NO +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +SORT_BRIEF_DOCS = NO +SORT_MEMBERS_CTORS_1ST = NO +SORT_GROUP_NAMES = NO +SORT_BY_SCOPE_NAME = NO +STRICT_PROTO_MATCHING = NO +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = YES +SHOW_FILES = YES +SHOW_NAMESPACES = YES +FILE_VERSION_FILTER = +LAYOUT_FILE = +CITE_BIB_FILES = +#--------------------------------------------------------------------------- +# Configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# Configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = . +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.h +RECURSIVE = YES +EXCLUDE = bin +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = +EXAMPLE_PATTERNS = * +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = +#--------------------------------------------------------------------------- +# Configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES +USE_HTAGS = NO +VERBATIM_HEADERS = YES +CLANG_ASSISTED_PARSING = NO +CLANG_OPTIONS = +#--------------------------------------------------------------------------- +# Configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +ALPHABETICAL_INDEX = YES +COLS_IN_ALPHA_INDEX = 5 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = NO +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = +HTML_EXTRA_FILES = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 +HTML_TIMESTAMP = NO +HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Doxygen generated docs" +DOCSET_BUNDLE_ID = org.doxygen.Project +DOCSET_PUBLISHER_ID = org.doxygen.Publisher +DOCSET_PUBLISHER_NAME = Publisher +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +CHM_INDEX_ENCODING = +BINARY_TOC = NO +TOC_EXPAND = NO +GENERATE_QHP = NO +QCH_FILE = +QHP_NAMESPACE = org.doxygen.Project +QHP_VIRTUAL_FOLDER = doc +QHP_CUST_FILTER_NAME = +QHP_CUST_FILTER_ATTRS = +QHP_SECT_FILTER_ATTRS = +QHG_LOCATION = +GENERATE_ECLIPSEHELP = NO +ECLIPSE_DOC_ID = org.doxygen.Project +DISABLE_INDEX = NO +GENERATE_TREEVIEW = NO +ENUM_VALUES_PER_LINE = 4 +TREEVIEW_WIDTH = 250 +EXT_LINKS_IN_WINDOW = NO +FORMULA_FONTSIZE = 10 +FORMULA_TRANSPARENT = YES +USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS +MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = +SEARCHENGINE = NO +SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = +#--------------------------------------------------------------------------- +# Configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4 +EXTRA_PACKAGES = +LATEX_HEADER = +LATEX_FOOTER = +LATEX_EXTRA_STYLESHEET = +LATEX_EXTRA_FILES = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +LATEX_SOURCE_CODE = NO +LATEX_BIB_STYLE = plain +#--------------------------------------------------------------------------- +# Configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +RTF_SOURCE_CODE = NO +#--------------------------------------------------------------------------- +# Configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = YES +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_SUBDIR = +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# Configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +DOCBOOK_PROGRAMLISTING = NO +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# Configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = DLL_PRIVATE= \ + DLL_PUBLIC= +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration options related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +MSCGEN_PATH = +DIA_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +DOT_NUM_THREADS = 0 +DOT_FONTNAME = Helvetica +DOT_FONTSIZE = 10 +DOT_FONTPATH = +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_PATH = +DOTFILE_DIRS = +MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = +PLANTUML_INCLUDE_PATH = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES diff --git a/libadhocutil/buffer.cpp b/libadhocutil/buffer.cpp index ba0774d..2ddca50 100644 --- a/libadhocutil/buffer.cpp +++ b/libadhocutil/buffer.cpp @@ -311,6 +311,12 @@ Buffer::operator!() const return content.empty(); } +bool +Buffer::empty() const +{ + return content.empty(); +} + std::ostream & std::operator<<(std::ostream & os, const Buffer & b) { diff --git a/libadhocutil/buffer.h b/libadhocutil/buffer.h index fa1b815..4a355fa 100644 --- a/libadhocutil/buffer.h +++ b/libadhocutil/buffer.h @@ -15,54 +15,96 @@ namespace std { DLL_PUBLIC std::ostream & operator<<(std::ostream &, const Buffer &); } +/// High-speed text buffer for easy creation of programatically created strings. class DLL_PUBLIC Buffer : public virtual IntrusivePtrBase { public: - enum CStringHandling { Use, Copy, Free }; + /** How should Buffer handle char * arguments? */ + enum CStringHandling { + /// Use the memory passed verbatim. + Use, + /// Copy the memory passed to it for it's own use. + Copy, + /// Use the memory passed verbatim and free it when finished. + Free + }; + /// Pointer typedef. typedef boost::intrusive_ptr<Buffer> Ptr; + /// Const pointer typedef. typedef boost::intrusive_ptr<const Buffer> CPtr; + /** Create an empty buffer */ Buffer(); + /** Create a buffer containing a single element from the given char * */ Buffer(const char * src, CStringHandling); + /** Create a buffer containing a single element from the given char * */ Buffer(char * src, CStringHandling); + /** Create a buffer containing a single element from the given std::string */ Buffer(const std::string &); ~Buffer(); + /** Append the given char * (will copy) */ Buffer & operator+=(const char * str); + /** Append the given std::string */ Buffer & operator+=(const std::string & str); + /** Replace all current content with the given char * (will copy) */ Buffer & operator=(const char * str); + /** Replace all current content with the given std::string */ Buffer & operator=(const std::string & str); + /** Replace all current content with the given Buffer's elements. Shallow copy as all elements are immutable. */ Buffer & operator=(const Buffer & str); + /** true if the buffer contains no elements (empty) */ bool operator!() const; - + /** true if the buffer contains no elements (non-empty) */ operator bool() const; + /** Converts all elements into a single flattened std::string */ operator std::string() const; + /** Converts all elements into a single flattened char * */ operator const char *() const; + /** + * Writes all elements in turn to the given buffer space, including a null terminator. + * @param buf Address of buffer to write into. + * @param bufSize Maximum number of bytes to write. + * @param off Effective starting position to copy from. + */ void writeto(char * buf, size_t bufSize, size_t off) const; + /** Write the Buffer to a std::ostream */ friend std::ostream & std::operator<<(std::ostream &, const Buffer &); + /** Append the given char * to the end of the buffer. */ Buffer & append(const char * str, CStringHandling h); + /** Append the given char * to the end of the buffer. */ Buffer & append(char * str, CStringHandling h); + /** Append the given std::string to the end of the buffer. */ Buffer & append(const std::string & str); + /** Append the given printf style format string and arguments to the buffer. */ Buffer & appendf(const char * fmt, ...) __attribute__((format (printf, 2, 3))); + /** Append the given printf style format string and va_list to the buffer. */ Buffer & vappendf(const char * fmt, va_list args); + /** Append the given boost::format style format string and arguments to the buffer. */ template <typename ... Params> Buffer & appendbf(const std::string & fmtstr, const Params & ... params) { return appendbf(*getFormat(fmtstr), params...); } + /** Append the given boost::format and arguments to the buffer. */ template <typename Param, typename ... Params> Buffer & appendbf(boost::format & fmt, const Param & param, const Params & ... params) { fmt % param; return appendbf(fmt, params...); } + /** Clear the Buffer of all content. */ Buffer & clear(); - + /** Get the total size of all elements. */ size_t length() const; + /** Test if the Buffer is empty. */ + bool empty() const; + /** Flattern the Buffer and return it as a std::string. */ std::string str() const; + /** Helper function to centralize the construction of boost::format instances. */ static boost::shared_ptr<boost::format> getFormat(const std::string & msgfmt); private: diff --git a/libadhocutil/cache.h b/libadhocutil/cache.h index b28c6dc..f2a4e81 100644 --- a/libadhocutil/cache.h +++ b/libadhocutil/cache.h @@ -10,6 +10,7 @@ #include <boost/thread/shared_mutex.hpp> #include <boost/variant.hpp> +/// @cond template <typename T, typename K> class Cacheable { public: @@ -47,20 +48,46 @@ class CallCacheable : public Cacheable<T, K> { struct byValidity {}; struct byKey {}; +/// @endcond + +/// In-memory cache of T, keyed by K. template <typename T, typename K> class Cache { public: + /// @cond typedef K Key; typedef T Value; typedef Cacheable<T, K> Item; typedef boost::shared_ptr<Item> Element; + /// @endcond + /** Construct a default empty cache. */ Cache(); + /** Add a known item to the cache. + * @param k The key of the cache item. + * @param t The item to cache. + * @param validUntil The absolute time the cache item should expire. + */ void add(const K & k, const T & t, time_t validUntil); + /** Add a callback item to the cache. + * The callback will be called on first hit of the cache item, at which + * point the return value of the function will be cached. + * @param k The key of the cache item. + * @param tf The callback function to cache. + * @param validUntil The absolute time the cache item should expire. + */ void add(const K & k, const boost::function<T()> & tf, time_t validUntil); + /** Get an Element from the cache. The element represents the key, item and expiry time. + * Returns null on cache-miss. + * @param k Cache key to get. */ Element getItem(const K & k) const; + /** Get an Item from the cache. Returns null on cache-miss. + * @param k Cache key to get. */ const T * get(const K & k) const; + /** Get the size of the cache (number of items). @warning This cannot be reliably used to + * determine or estimate the amount of memory used by items in the cache without further + * knowledge of the items themselves. */ size_t size() const; private: diff --git a/libadhocutil/cache.impl.h b/libadhocutil/cache.impl.h index c47eabf..7d4119d 100644 --- a/libadhocutil/cache.impl.h +++ b/libadhocutil/cache.impl.h @@ -5,6 +5,7 @@ #include <boost/lambda/lambda.hpp> #include "lockHelpers.h" +/// @cond template<typename T, typename K> Cacheable<T, K>::Cacheable(const K & k, time_t vu) : key(k), @@ -127,6 +128,7 @@ Cache<T, K>::prune() const lastPruneTime = now; } } +/// @endcond #endif diff --git a/libadhocutil/curlHandle.h b/libadhocutil/curlHandle.h index 0bdcd11..de5d812 100644 --- a/libadhocutil/curlHandle.h +++ b/libadhocutil/curlHandle.h @@ -5,35 +5,50 @@ #include "intrusivePtrBase.h" #include "visibility.h" +/// libcurl handle wrapper. +/** Wraps a libcurl CURL * object in a C++ friendly manner. */ class DLL_PUBLIC CurlHandle : public virtual IntrusivePtrBase { public: + /** + * Create a new CurlHandle. + * @param url Set the required CURLOPT_URL property to the given url. + */ CurlHandle(const std::string & url); virtual ~CurlHandle(); - CurlHandle(const CurlHandle &) = delete; - void operator=(const CurlHandle &) = delete; - + /** Set option wrapper. */ template <typename T> void setopt(CURLoption opt, const T val); + /** Get info for long values */ void getinfo(CURLINFO info, long & val) const; + /** Get info for int values (avoids ambiguous call errors for ease of use) */ void getinfo(CURLINFO info, int & val) const; + /** Get info for double values */ void getinfo(CURLINFO info, double & val) const; + /** Get info for char * values */ void getinfo(CURLINFO info, char * & val) const; + /** Append the given HTTP header */ void appendHeader(const char *); + /** Append the given HTTP post content */ void appendPost(const char *, const char *); + /** Perform the CURL transfer. */ void perform(); + /** Get the underlying CURL * handle. @warning Make changes at your own risk. */ operator CURL *() const; protected: + /// @cond void checkCurlCode(CURLcode res) const; CURL * curl_handle; curl_slist * curl_headers; curl_httppost * postS, * postE; + /// @endcond }; typedef boost::intrusive_ptr<CurlHandle> CurlHandlePtr; +/// @cond template <> void CurlHandle::setopt(CURLoption opt, const void * val); template <> @@ -45,6 +60,7 @@ void CurlHandle::setopt(CURLoption opt, const T val) { setopt(opt, (const void *)val); } +/// @endcond #endif diff --git a/libadhocutil/curlMultiHandle.h b/libadhocutil/curlMultiHandle.h index 0f70988..14242c6 100644 --- a/libadhocutil/curlMultiHandle.h +++ b/libadhocutil/curlMultiHandle.h @@ -11,24 +11,25 @@ class RunningCurl; typedef boost::intrusive_ptr<RunningCurl> RunningCurlPtr; +/// Perform multiple CURL operations at once. class DLL_PUBLIC CurlMultiHandle : public IntrusivePtrBase { public: - typedef std::set<RunningCurlPtr> CURLs; + /** A function that should consume the inbound byte stream. */ typedef boost::function<void(std::istream &)> Consumer; CurlMultiHandle(); ~CurlMultiHandle(); - CurlMultiHandle(const CurlMultiHandle &) = delete; - void operator=(const CurlMultiHandle &) = delete; - + /** Adds a new consumer for the given URL to the set of operations to perform. */ CurlHandlePtr addCurl(const std::string &, const Consumer &); + /** Perform all queued operations. */ void performAll(); private: + typedef std::set<RunningCurlPtr> CURLs; typedef std::map<CURL *, RunningCurlPtr> Running; - DLL_PRIVATE void addRunner(CURLM * curlm, Running & running, CurlMultiHandle::CURLs & curls); + DLL_PRIVATE void addRunner(CURLM * curlm, Running & running, CURLs & curls); CURLs curls; }; diff --git a/libadhocutil/curlStream.h b/libadhocutil/curlStream.h index 2528bd8..3a131f5 100644 --- a/libadhocutil/curlStream.h +++ b/libadhocutil/curlStream.h @@ -8,10 +8,13 @@ #include "visibility.h" #include "curlHandle.h" +/// boost::iostreams::source implementation for CURL downloads. class DLL_PUBLIC CurlStreamSource : public boost::iostreams::source, public CurlHandle, RuntimeContext { public: + /** Construct a new stream source for the given URL. */ CurlStreamSource(const std::string & url); + /** Required member function for reading of the stream source by boost::iostreams::stream. */ std::streamsize read(char * target, std::streamsize targetSize); private: diff --git a/libadhocutil/intrusivePtrBase.h b/libadhocutil/intrusivePtrBase.h index b5fa94e..327ac5a 100644 --- a/libadhocutil/intrusivePtrBase.h +++ b/libadhocutil/intrusivePtrBase.h @@ -3,8 +3,10 @@ #include <boost/intrusive_ptr.hpp> +/// Base class suitable for use with boost::intrusive_ptr<T>. class IntrusivePtrBase { protected: + /// @cond inline IntrusivePtrBase() : _refCount(0) { } inline virtual ~IntrusivePtrBase() = 0; @@ -37,6 +39,7 @@ intrusive_ptr_add_ref(const IntrusivePtrBase * p) { p->_refCount += 1; } +/// @endcond #endif diff --git a/libadhocutil/lazyPointer.h b/libadhocutil/lazyPointer.h index 2aed50e..79808b7 100644 --- a/libadhocutil/lazyPointer.h +++ b/libadhocutil/lazyPointer.h @@ -5,36 +5,49 @@ #include <boost/variant.hpp> #include <boost/intrusive_ptr.hpp> +/// Smart pointer that initializes itself only if it has to. +/** + * LazyPointer behaves like a normal smarter for the most part. It's benefit + * is that it can be assigned a factory function which is only called on + * an attempt to dereference the pointer. All such operations will call + * this factory function as required prior to evaluating the pointer's value. + */ template <typename T, typename P = boost::intrusive_ptr<T>> class LazyPointer { public: + /// @cond typedef T element_type; typedef P pointer_type; typedef boost::function0<P> Factory; typedef boost::variant<P, Factory> Source; + /// @endcond - // Constructors + /** Construct pointer with a factory function. */ LazyPointer(const Factory & f) : source(f) { } + /** Construct pointer with an instance value. */ LazyPointer(const P & p) : source(p) { } + /** Construct pointer with an instance value. */ LazyPointer(T * p) : source(P(p)) { } + /** Construct pointer with no factory or value. */ LazyPointer() : source(P(NULL)) { } // Getters + /// @cond operator P() const { return deref(); @@ -105,7 +118,9 @@ class LazyPointer { source = f; return *this; } + /// @endcond + /** Does the lazy pointer have a value? (as opposed to a factory). */ bool hasValue() const { return boost::get<P>(&source); diff --git a/libadhocutil/lockHelpers.h b/libadhocutil/lockHelpers.h index c583421..5ac4bf7 100644 --- a/libadhocutil/lockHelpers.h +++ b/libadhocutil/lockHelpers.h @@ -1,6 +1,7 @@ #ifndef ADHOCUTIL_LOCKHELPERS_H #define ADHOCUTIL_LOCKHELPERS_H +/// @cond template <typename locktype> class _LockLoop { public: @@ -18,6 +19,7 @@ class _LockLoop { locktype lock; bool flag; }; +/// @endcond #define LIBADHOC_LOCK_CONCAT2(a, b) a ## b #define LIBADHOC_LOCK_CONCAT(a, b) LIBADHOC_LOCK_CONCAT2(a, b) diff --git a/libadhocutil/nvpParse.h b/libadhocutil/nvpParse.h index 75cadef..354046d 100644 --- a/libadhocutil/nvpParse.h +++ b/libadhocutil/nvpParse.h @@ -13,8 +13,15 @@ #endif #include <visibility.h> +/// Name=Value parser. +/** + * Parses an input stream of the format Name=Value;Name2=Value2;... into a predefined object + * structure. + */ class NvpParse : public yyFlexLexer { public: + /// @cond + /// Thrown in the event of the input referring to a member that doesn't exist. class ValueNotFound : public std::runtime_error { public: ValueNotFound(const std::string &); @@ -47,10 +54,16 @@ class NvpParse : public yyFlexLexer { private: V T::*target; }; + /// @endcond #define NvpTarget(T) std::map<std::string, boost::shared_ptr<NvpParse::TargetBase<T>>> #define NvpValue(c, m) { #m, boost::shared_ptr<NvpParse::Target<c, decltype(c::m)>>(new NvpParse::Target<c, decltype(c::m)>(&c::m)) } + /** Parse an input stream into the given object. + * @param in The input stream. + * @param tm The Target Map for the object. + * @param t The target instance to populate. + */ template <typename T> static void parse(std::istream & in, const NvpTarget(T) & tm, T & t) { @@ -61,6 +74,9 @@ class NvpParse : public yyFlexLexer { return parse(in, am); } + /** Don't use this function directly, instead use: + * @code {.cpp} void parse(std::istream & in, const NvpTarget(T) & tm, T & t) @endcode + */ DLL_PUBLIC static void parse(std::istream & in, const AssignMap & m); private: diff --git a/libadhocutil/processPipes.h b/libadhocutil/processPipes.h index a1d0800..42efbe7 100644 --- a/libadhocutil/processPipes.h +++ b/libadhocutil/processPipes.h @@ -5,26 +5,33 @@ #include <string> #include "visibility.h" -/** - * Spawn a new process, providing access to it's stdin and stdout - * @param params path and arguments to spawn (copied and passed to execv) - * @param fds (out) the FDs on the childs stdin(0) and stdout(1) - * @return the process ID of the child - */ +/// Spawn a process and attach to its IO handles. class DLL_PUBLIC ProcessPipes { public: + /** + * Spawn a new process, providing (optional) access to its stdin, stdout and + * stderr file handles. + * @param args path and arguments to spawn (passed to execv) + * @param in Attach to stdin? + * @param out Attach to stdout? + * @param err Attach to stderr? + */ ProcessPipes(const std::vector<std::string> & args, bool in, bool out, bool err); ~ProcessPipes(); - ProcessPipes(const ProcessPipes &) = delete; - void operator=(const ProcessPipes &) = delete; - + /** FD handle to child's stdin. */ int fdIn() const; + /** FD handle to child's stdout. */ int fdOut() const; + /** FD handle to child's stderr. */ int fdError() const; + /** Process id of child. */ pid_t pid() const; private: + ProcessPipes(const ProcessPipes &) = delete; + void operator=(const ProcessPipes &) = delete; + int in, out, error; pid_t child; }; diff --git a/libadhocutil/runtimeContext.h b/libadhocutil/runtimeContext.h index b7ce0a3..21c6fe6 100644 --- a/libadhocutil/runtimeContext.h +++ b/libadhocutil/runtimeContext.h @@ -5,15 +5,27 @@ #include <ucontext.h> #include "visibility.h" +/// Runtime Context +/** + * Create an alternate stack for processing. + */ class DLL_PUBLIC RuntimeContext { public: + /** + * Create a new RuntimeContent + * @param stacksize The size in bytes of the new stack. + */ RuntimeContext(size_t stacksize = 16384); - virtual ~RuntimeContext(); + virtual ~RuntimeContext() = 0; + /** Swap to/from the contained stack. */ void swapContext(); + + /** Has the callback on the contained stack run to completion? */ bool hasCompleted() const; protected: + /** Overridden in a sub-class to implement functionality in the alternate stack */ DLL_PRIVATE virtual void callback() = 0; private: diff --git a/libadhocutil/scopeExit.h b/libadhocutil/scopeExit.h index 7534add..dc2a286 100644 --- a/libadhocutil/scopeExit.h +++ b/libadhocutil/scopeExit.h @@ -4,10 +4,19 @@ #include <boost/function.hpp> #include "visibility.h" +/// Run code at scope exit. class DLL_PUBLIC ScopeExit { public: + /** Callback for code to be run. */ typedef boost::function<void()> Event; - ScopeExit(const Event &, const Event & = Event(), const Event & = Event(), const Event & = Event()); + + /** Construct a trigger for running code at scope exit. + * @param pre Run this code (unconditionally) first. + * @param success Only run this if the scope is exitted cleanly. + * @param failure Only run this if the scope is exitted because of an uncaught exception. + * @param post Run this code (unconditionally) last. + */ + ScopeExit(const Event & pre, const Event & success = Event(), const Event & failure = Event(), const Event & post = Event()); ~ScopeExit(); ScopeExit(const ScopeExit &) = delete; |