Copyright © 2007 Majoron.com
| Revision History | |
|---|---|
| Revision 1.0 | 2007.11.14 |
|
First published revision | |
Table of Contents
The project AuxUtils is an auxiliary C++ library that implements the functionality which doesn't exists or had limitations in the Boost libraries. The library provides some efficient functions and templates, wrap some platforms dependent functions.
Officially supported platforms are Windows, and Linux. The AuxUtils library may be ported to other platforms by demand.
Supported language is C++.
This document describes version 1.0 of the AuxUtils library. It has list the goals and objectives to archive, contains library implementation overview and a few examples and tutorials in order to begin to use library in application easy.
AuxUtils library intended for designed and developers of the software applications that have some restriction or limitation at Boost functionality, which AuxUtils is eliminated.
This section describes how to obtain and install AuxUtils library. A summary of the procedure follows and later sections provide the details.
The AuxUtils installation procedure depends on distribution package type and platforms on which distribution you will install.
The immediate following sections contain the information necessary to choose, download and verify you distribution. The instructions in the later sections describe how to install the distribution that you choose. For binary distributions, see the instructions at section "Installation from binaries" for appropriate operation system or installation type (RPM or DEB). To build AuxUtils from source codes see the instruction at section "Installation from sources" for appropriate operation system. To install AuxUtils from development tree see the instruction at section "Installation from development tree".
Officially supported platforms are:
Windows
Linux
GNU Autoconf and Automake are used to build AuxUtils on Unix-like operation systems, so it is possible to port AuxUtils to all moderns operation systems that have a C++ compiler and dependent packages.
Check out our download page at www.majoron.com for information about the current version binary or source distributions and for downloading instructions. You can download these packages from primary site www.majoron.com or select appropriate mirrors at www.sourceforge.net.
Obtaining the development three isn't possible for now. But will be added in the nearest future.
After you have downloaded the AuxUtils package that suits you needs and before you attempt to install it, you should make sure that it is intact and has not been tampered with. There are a few means of the integrity checking:
MD5 checksums
For RPM packages, the built-in RPM integrity verification mechanism
After you have downloaded a AuxUtils package, you should make sure that its MD5 checksum matches the one provided on the AuxUtils download pages. Each package has an individual checksum that you can verify with the following command, where package_name is the name of the package you downloaded:
shell> md5sum package_name
Example 1. Verifying MD5 checksums
shell>md5sum libAuxUtils-src-1.0.0.tar.bz2
shell> aaab65abbec64d5e907dcd41b8699945 AuxUtils-src-1.0.0.tar.bz2
You should verify that the resulting checksum (the string of hexadecimal digits) matches the one displayed on the download page immediately below the respective package.
Note that not all operating systems support the md5sum command. On some, it is simply called md5, and others do not ship it at all. On Linux, it is part of the GNU Text Utilities package, which is available for a wide range of platforms. You can download the source code from http://www.gnu.org/software/textutils/ as well. If you have OpenSSL installed, you can use the command openssl md5 package_name instead. A Windows implementation of the md5 command line utility is available from http:// www.fourmilab.ch/md5/. winMd5Sum is a graphical MD5 checking tool that can be obtained from http:// www.nullriver.com/index/products/winmd5sum.
For RPM packages, there is no separate signature. RPM packages have a built-in GPG signature and MD5 checksum. You can verify a package by running the following command::
shell> rpm --checksig package_name.rpm
Example 2. Signature checking using RPM
shell> rpm --checksig libAuxUtils-1.0-linux-2.6-intel.rpm
libAuxUtils-1.0-linux-2.6-intel.rpm: sha1 md5 OK
This section describe the default layout of the directories created by installing binary or source distributions provided at Majoron. A distributions provided by another vendor might use layout different from those shown here.
Denote AUXUTILS_ROOT as installation directory of the AuxUtils project. The installation directory has the following subdirectories:
Table 1. Windows installation layouts
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/docs | AuxUtils documentation. |
| AUXUTILS_ROOT/include | Header files to include at you projects. |
| AUXUTILS_ROOT/include/dynmod | Header files to work with dynamical modules. |
| AUXUTILS_ROOT/include/ept | Header files to work thread pools, timers and object pools. |
| AUXUTILS_ROOT/include/io | Header files to work with IO routines. |
| AUXUTILS_ROOT/include/ipc | Header files to work with IPC routines. |
| AUXUTILS_ROOT/include/utils | Header files that contains some utilities. |
| AUXUTILS_ROOT/lib | Libraries files to link with you applications. |
On Unix-like operation systems sources distribution after building and installing, binary distribution and RPM or DEB distributions after installing create similar directory layouts.By default, but you can configure installation location, the installation step installs files under /usr/local, in the following subdirectories:
Table 2. Unix-like installation layouts
| Directory | Content of the directory |
|---|---|
| /usr/local/include/AuxUtils | Header files to include at you projects. |
| /usr/local/include/AuxUtils/dynmod | Header files to work with dynamical modules. |
| /usr/local/include/AuxUtils/ept | Header files to work thread pools, timers and object pools. |
| /usr/local/include/AuxUtils/io | Header files to work with IO routines. |
| /usr/local/include/AuxUtils/ipc | Header files to work with IPC routines. |
| /usr/local/include/AuxUtils/utils | Header files that contains some utilities. |
| /usr/local/lib/AuxUtils | Libraries files to link with you applications. |
After extracting a sources distribution to AUXUTILS_ROOT, it will have the following subdirectories:
Table 3. Sources distribution layouts
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/AuxUtils/ | AuxUtils project files needed to use it in own projects. |
| AUXUTILS_ROOT/Documents/ | AuxUtils manual and others documentations. |
| AUXUTILS_ROOT/Snippets/ | Code snippets of the usage AuxUtils library.. |
| AUXUTILS_ROOT/TestDynmod/ | The simplest dynamical module to test AuxUtils library. |
| AUXUTILS_ROOT/UnitTests/ | Unit test to check AuxUtils library. |
| AUXUTILS_ROOT/Workspaces/ | Workspaces for building projects. |
To use AuxUtils at you project you need files located at AUXUTILS_ROOT/AuxUtils and has the following subdirectories:
Table 4. AuxUtils layouts
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/AuxUtils/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/AuxUtils/include | Header files to include at you projects. |
| AUXUTILS_ROOT/AuxUtils/include/dynmod | Header files to work with dynamical modules. |
| AUXUTILS_ROOT/AuxUtils/include/ept | Header files to work thread pools, timers and object pools. |
| AUXUTILS_ROOT/AuxUtils/include/io | Header files to work with IO routines. |
| AUXUTILS_ROOT/AuxUtils/include/ipc | Header files to work with IPC routines. |
| AUXUTILS_ROOT/AuxUtils/include/utils | Header files that contains some utilities. |
| AUXUTILS_ROOT/AuxUtils/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/AuxUtils/src | Source files of the AuxUtils project. |
| AUXUTILS_ROOT/AuxUtils/src/dynmod | Source files to work with dynamical modules. |
| AUXUTILS_ROOT/AuxUtils/src/ept | Source files to work thread pools, timers and object pools. |
| AUXUTILS_ROOT/AuxUtils/src/io | Source files to work with IO routines. |
| AUXUTILS_ROOT/AuxUtils/src/ipc | Source files to work with IPC routines. |
| AUXUTILS_ROOT/AuxUtils/src/utils | Source files that contains some utilities. |
Code snippets how to use AuxUtils located at AUXUTILS_ROOT/Snippets and has the following subdirectories:
Table 5. Snippets layouts (part I)
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/Snippets/ByteBuffer | ByteBuffer snippet. |
| AUXUTILS_ROOT/Snippets/ByteBuffer/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/ByteBuffer/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/ByteBuffer/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/ByteBuffer/src | Sources file of the snippet. |
| AUXUTILS_ROOT/Snippets/DynamicModule | DynamicModule snippet. |
| AUXUTILS_ROOT/Snippets/DynamicModule/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/DynamicModule/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/DynamicModule/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/DynamicModule/src | Sources file of the snippet. |
| AUXUTILS_ROOT/Snippets/ObjectPool | ObjectPool snippet. |
| AUXUTILS_ROOT/Snippets/ObjectPool/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/ObjectPool/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/ObjectPool/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/ObjectPool/src | Sources file of the snippet. |
Table 6. Snippets layouts (part II)
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/Snippets/OSProcess | OSProcess snippet. |
| AUXUTILS_ROOT/Snippets/OSProcess/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/OSProcess/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/OSProcess/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/OSProcess/src | Sources file of the snippet. |
| AUXUTILS_ROOT/Snippets/PipedStream | PipedStream snippet. |
| AUXUTILS_ROOT/Snippets/PipedStream/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/PipedStream/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/PipedStream/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/PipedStream/src | Sources file of the snippet. |
| AUXUTILS_ROOT/Snippets/SequenceGenerator | SequenceGenerator snippet. |
| AUXUTILS_ROOT/Snippets/SequenceGenerator/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/SequenceGenerator/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/SequenceGenerator/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/SequenceGenerator/src | Sources file of the snippet. |
Table 7. Snippets layouts (part III)
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/Snippets/SharedCondition | SharedCondition snippet. |
| AUXUTILS_ROOT/Snippets/SharedCondition/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/SharedCondition/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/SharedCondition/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/SharedCondition/src | Sources file of the snippet. |
| AUXUTILS_ROOT/Snippets/SharedMemory | SharedMemory snippet. |
| AUXUTILS_ROOT/Snippets/SharedMemory/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/SharedMemory/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/SharedMemory/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/SharedMemory/src | Sources file of the snippet. |
| AUXUTILS_ROOT/Snippets/SharedMutex | SharedMutex snippet. |
| AUXUTILS_ROOT/Snippets/SharedMutex/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/SharedMutex/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/SharedMutex/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/SharedMutex/src | Sources file of the snippet. |
Table 8. Snippets layouts (part IV)
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/Snippets/SharedSemaphore | SharedSemaphore snippet. |
| AUXUTILS_ROOT/Snippets/SharedSemaphore/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/SharedSemaphore/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/SharedSemaphore/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/SharedSemaphore/src | Sources file of the snippet. |
| AUXUTILS_ROOT/Snippets/ThreadPool | ThreadPool snippet. |
| AUXUTILS_ROOT/Snippets/ThreadPool/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/ThreadPool/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/ThreadPool/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/ThreadPool/src | Sources file of the snippet. |
| AUXUTILS_ROOT/Snippets/Timer | Timer snippet. |
| AUXUTILS_ROOT/Snippets/Timer/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/Snippets/Timer/include | Header files of the snippet. |
| AUXUTILS_ROOT/Snippets/Timer/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/Snippets/Timer/src | Sources file of the snippet. |
The simplest dynamical module is located at AUXUTILS_ROOT/TestDynmod and has the following subdirectories:
Table 9. TestDynmod layouts
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/TestDynmod/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/TestDynmod/include | Header files to include at you projects. |
| AUXUTILS_ROOT/TestDynmod/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/TestDynmod/src | Sources file of the AuxUtils project. |
Unit tests to verify library located at AUXUTILS_ROOT/UnitTests and has the following subdirectories:
Table 10. UnitTest layouts
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/UnitTests/docs | Doxygen files to create APIs. |
| AUXUTILS_ROOT/UnitTests/include | Header files to include at you projects. |
| AUXUTILS_ROOT/UnitTests/res | Resources file dependents on operation system. |
| AUXUTILS_ROOT/UnitTests/src | Sources file of the AuxUtils project. |
Workspaces to build library from source located at AUXUTILS_ROOT/Worspaces and has the following subdirectories:
Table 11. Workspaces layouts
| Directory | Content of the directory |
|---|---|
| AUXUTILS_ROOT/Workspaces/autotools | Workspaces for building projects by GNU Autoconf and Automake tools. |
| AUXUTILS_ROOT/Workspaces/distrib | Workspaces for building projects and create distribution packages. |
| AUXUTILS_ROOT/Workspaces/eclipse | Workspaces for building projects by Eclipse development IDE. |
| AUXUTILS_ROOT/Workspaces/msvc8 | Workspaces for building projects by MSVC 8.x. |
| AUXUTILS_ROOT/Workspaces/msvc9 | Workspaces for building projects by MSVC 9.x. |
The immediate following sections describe how to install AuxUtils library from binary distribution under different platforms.
Unpack distribution package using archivator, for example WinZip, to destination directory.
Unpack distribution package using archivator to destination directory. You can use tar command to unpack distribution, where pachage_am is the name of the package you downloaded.
shell> tar -xjvf package_name
The recommended way to install AuxUtils on RPM-based Linux distributions is by using the RPM packages. The RPMs provided by Majoron to the community should work on all versions of Linux that support RPM packages. To obtain RPM packages, see section "How to get AuxUtils".
To install RPM distribution you can use rpm command, where package_name is the name of the package you downloaded:
shell> rpm -i package_name
The recommended way to install AuxUtils on DEB-based Linux distributions is by using the DEB packages. The DEBs provided by Majoron to the community should work on all versions of Linux that support DEB packages. To obtain DEB packages, see section "How to get AuxUtils".
To install DEB distribution you can use dpkg command, where package_name is the name of the package you downloaded:
shell> dpk - i package_name
The immediate following sections describe how to build and install AuxUtils library from source distribution under different platforms.
Unpack distribution package using archivator, for example WinZip, to destination directory. After unpacking distribution you need a build library. In order to do it, select suitable projects file from Workspaces directory and build library.
Unpack distribution package using archivator to destination directory. You can use tar command to unpack distribution, where pachage_am is the name of the package you downloaded.
shell> tar -xjvf package_name
After unpacking a distribution package you need to build it. To do it use GNU Autoconf and Automake files that located at Worspaces/autotools directory. After a building you may optionally to install header files and libraries.
Obtaining the development three and hence installation based on development three isn't possible for now. But will be added in the nearest future.
Before posting a bug report about a problem, please try to verify that it is a bug and that it has not been reported already:
Start by searching the AuxUtils online manual at www.majoron.com. We try to keep the manual up to date by updating it frequently with solutions to newly found problems. The change history located at www.majoron.com can be particularly useful since it is quite possible that a newer version contains a solution to your problem.
For solutions to some common problems, see chapter 7: "Problems and common errors". This chapter contains information about well-known problems.
Search the bugs database at www.majoron.com to see whether the bug has been reported and fixed.
Search the forums database at www.majoron.com to see related threads. Here you could discuss the problems with other user and get a help.
If you can't find an answer in the manual, the bugs database, or the forum, please use the following guidelines for reporting the bug. The normal way to report bugs is to visit www.majoron.com/, which is the address for our bugs database. This database is public and can be browsed and searched by anyone. If you log in to the system, you can enter new reports to the bugs database.
Writing a good bug report takes patience, but doing it right the first time saves time both for us and for yourself. A good bug report, containing a full test case for the bug, makes it very likely that we will fix the bug in the next release. This section helps you write your report correctly so that you don't waste your time doing things that may not help us much or at all. Please read this section carefully and make sure that all the information described here is included in your report.
It is most helpful when a good description of the problem is included in the bug report. That is, give a good example of everything you did that led to the problem and describe, in exact detail, the problem itself. The best reports are those that include a full example showing how to reproduce the bug or problem.
Remember that it is possible for us to respond to a report containing too much information, but not to one containing too little. People often omit facts because they think they know the cause of a problem and assume that some details don't matter. A good principle to follow is that if you are in doubt about stating something, state it. It is faster and less troublesome to write a couple more lines in your report than to wait longer for the answer if we must ask you to provide information that was missing from the initial report.
The most common errors made in bug reports are (a) not including the version number of the AuxUtils distribution that you use, and (b) not fully describing the platform on which the AuxUtils library is installed (including the platform type and version number). These are highly relevant pieces of information, and in 99 cases out of 100, the bug report is useless without them. Very often we get questions like, “Why doesn't this work for me?” Then we find that the feature requested wasn't implemented in that AuxUtils version, or that a bug described in a report has been fixed in newer AuxUtils versions. Errors often are platform-dependent. In such cases, it is next to impossible for us to fix anything without knowing the operating system and the version number of the platform.
If you compiled AuxUtils from source, remember also to provide information about your compiler if it is related to the problem. Often people find bugs in compilers and think the problem is AuxUtils-related. Most compilers are under development all the time and become better version by version. To determine whether your problem depends on your compiler, we need to know what compiler you used. Note that every compiling problem should be regarded as a bug and reported accordingly.
Please include the following information in your report:
The version number of the AuxUtils distribution you are using (for example, AuxUtils-1.0). You can find out which version you are using at the name of the distribution.
The manufacturer and model of the machine on which you experience the problem.
The operating system name and version. If you work with Windows, you can usually get the name and version number by double-clicking your My Computer icon and pulling down the “Help/About Windows” menu. For most Unix-like operating systems, you can get this information by executing the command uname -a.
Sometimes the amount of memory (real and virtual) is relevant. If in doubt, include these values.
If you are using a source distribution of the AuxUtils, include the name and version number of the compiler that you used. If you have a binary distribution, include the distribution name.
If the problem occurs during compilation, include the exact error messages and also a few lines of context around the offending code in the file where the error occurs.
If you have a patch for a bug, do include it. But don't assume that the patch is all we need, or that we can use it, if you don't provide some necessary information such as test cases showing the bug that your patch fixes. We might find problems with your patch or we might not understand it at all. If so, we can't use it. If we can't verify the exact purpose of the patch, we won't use it. Test cases help us here. Show that the patch handles all the situations that may occur. If we find a borderline case (even a rare one) where the patch won't work, it may be useless.
Guesses about what the bug is, why it occurs, or what it depends on are usually wrong. Even the AuxUtils team can't guess such things without first using a debugger to determine the real cause of a bug.
If possible, download and install the most recent version of AuxUtils and check whether it solves your problem. All versions of the AuxUtils library are thoroughly tested and should work without problems. We believe in making everything as backward-compatible as possible, and you should be able to switch AuxUtils versions without difficulty.
Before posting a feature request, please try to verify that it has not been reported already:
See appendix: "Project Roadmap" to that feature request has not been included at roadmap already. Also please visit online roadmap at www.majoron.com to check at the latest version..
Search the forums database at www.majoron.com to see has this feature request discussed already.
Search the bugs database at www.majoron.com to see has this feature request discussed already.
In case this feature request is not included at roadmap yet and after researching the bugs database and forums you are sure that it is useful than submit it bugs database located at www.majoron.com. Don't forget setup Severity at enhancement value. Please include the following information in your feature request demand:
Use case of the feature request.
Why do you think that it is a responsibility of the AuxUtils?
How are you going to use it?
Why do you think it will be useful for others users?
This chapter contains information about base library objects. It covers what exists at AuxUtils library and if necessary that it covers implementation topics. AuxUtils library consists a few parts, which are discussed in the following sections.
This section overview a dynamic modules routines implemented at AuxUtils.
Dynamic module routines server to load a dynamic module. The module is a library that implemented as a dynamic(.dll) on Windows or shared(.so) on Unix-like system library .
The functionality implemented in a follow classes:
This section overview a EPT routines implemented at AuxUtils.
EPT routines server to work with a times, thread pools and pool objects. These routines allow to execute task on thread pool and subscribe timers.
The functionality implemented in a follow classes:
IObjectPoolItemFactory This class is an interface to pol item factory. It is declare create, reset and destroy interface.
ObjectPool Objects pool shares the object instances for more efficiently using memory management. Objects instance in pool are never recreated.
ObjectPoolPtrItemFactory implement IObjectPoolItemFactory interface to work with object which was created at memory heap.
thread pool This class encapsulate working with tasks. It allow to reserve a some threads to execute specified task. Also it has functionality to manage increase and decrease the quantity of the thread inside. Also it has flexible mechanism to assign a specified task thread to reduce hardware loading.
Timer Class time implement itself times and allow to work with times: create new timer, receive notification about time-out and cancel subscribed before timer.
This section overview a IO routines implemented at AuxUtils.
IO routines server to work with a data to transfers, streams.
The functionality implemented in a follow classes:
ByteArrayInputOutputStream This class implement IInputStream and IOutput stream interface. It is convenient as duplex stream: it allow to read data from a stream and write data into stream. Such types of the behaviour useful for using in protocols tasks .
ByteBuffer This class is a buffer and has method to work with data inside: append new data or cut current data and etc. Also it allow to manage increasing and decreasing the memory consumption and reserving memory. This class allow to work with external memory buffers or can manage own buffer inside.
IInputStream This class declare interface to work with input stream. It allow to write a portions of data into stream. It allow to write a portion of the data to stream.
IOutputStream This class declare interface to work with output stream. It allow to read a portion of the data from stream. Also class declare appropriate interface to check is it some data inside steam to read.
StreamReframer This class allow to re framer a stream. For example one source send packets with size 1024Kb at network, but destination require packet with size at 2048Kb. There is a task to re framer received packets before sent. This class allow to do it.
This section overview a IPC routines implemented at AuxUtils.
IPC routines server to work with a inter process communication. These routines wrap primitives to work with a shared memory to cross platforms classes.
The functionality implemented in a follow classes:
SharedCondition This class encapsulate shared condition inside. It has boost like interface to work with. There isn't implementation at boos library such synchronization primitive.
SharedMemoryThis class encapsulate shared memory inside. It has boost like interface to work with. There isn't implementation at boos library such synchronization primitive.
SharedMutex This class encapsulate shared mutex inside. It has boost like interface to work with. There isn't implementation at boos library such synchronization primitive.
SharedSemaphoreThis class encapsulate shared semaphore inside. It has boost like interface to work with. There isn't implementation at boos library such synchronization primitive.
This section overview a utility routines implemented at AuxUtils.
Utils routines server to work with sequence generator, operation system process and time.
The functionality implemented in a follow classes:
OSProcTools This routines encapsulate working with processes and port across different platforms. These routines allow to start new process and wait until started before process will be finished.
OSTimeTools This routines simplify to working with boost time functions. They are adapters to boost on which they are based.
SequenceGenerator This class is a sequence generator to create new id. It is flexible to configure strategy to receive a new identity. This allow to created new id one by one, or with some gaps. As template parameter it accepted any class which has right interface. Also this class has default template parameter which implement default behaviour.
Version This class is an auxiliary and allow to work with module versions.
AuxUtils is a well-documented library. A lost of examples provided at [1] document. Also the good way to understand how these entities are working is unit test. Almost all functionality has appropriate unit test. This examples illustrate how to use a AuxUtils library at different aspects. Among examples are:
Place here information about snippets and where they coud be founded
This snippet illustrates how to use byte buffer. The represantion for byte buffer with the specified capacity and len. The capacity/len can be changed at runtime without lost data.
This snippet illustrates how to use dynamic module. Dynmod provide a support for dynamically loading shared libraries with the specific implementation based on standard API with versioning (checking API versions) and standard lifecycle methods (single init & finalization library, creating an instance of object, looking up object by class name).
This snippet illustrates how to use object pool. Objects pool shares the object instances for more efficiently using memory management. Objects instance in pool are never recreated.
This snippet illustrates how to use os processes. The snippet start a new process asynchronous and wait until it is finished.
This snippet illustrates how to use piped io stream. Implementation of piped I/O stream based on slices of byte arrays. This implementation able to put ByteArray's and reading ByteArray's with the different lens. Block size per slice can be specified in the constructor when creation instance
This snippet illustrates how to use sequence generator. A simple sequence generator are used for generate integral identifiers. Current implementation able to create the simple unbounded generator (bounded only by base template data type) and create the bounded by min/max sequence generator.
This snippet illustrates how to use shared condition. SharedCondition is an IPC primitive for synchronization and represent functionality like boost::condition.
This snippet illustrates how to use shared memory. SharedMemory is an IPC primitive for exchanging user data and hides OS specific implementation.
This snippet illustrates how to use shared memory. SharedMutex is an IPC primitive for synchronization. SharedMutex must be used as boost::mutex primitive.
This snippet illustrates how to use shared semaphore. SharedSemaphore is an IPC primitive for synchronization. SharedSemaphore can be used with boost scoped lock or manually controlled.
This snippet illustrates how to use thread pool. The simple thread pool concept implementation
This chapter contains information about common problems and errors and has three sections. The first section contains common and well-know problems and solutions for it. The second section contains information about installation problems and solution for it. The last one contain information about known bugs at current release.
Here is installation issues problems and it's solutions.
Here is well-known problems and it's solutions.
To see the latest list of the known please visit the Kwon bugs page at www.majoron.com. This page contain the latest information.
Follow notation is used at change log. Each entry begin with a version, for which entry for created. Then follow component at {}. Then follow category of the bug at []. It can be bug report, feature request and etc. Than follow bug number at bug tracking system between // signs. And then follow a description of the entry. For example entry 1.0 { AntHill Core } [ Feature Request ] / 380 / STLport support mean than entry was created for 1.0 version of the AntHill Core component and entry is feature request with 380 number at bug tracking system to support STLPort library.
To see the latest list of the frequently asked questions please visit the F.A..Q. page at www.majoron.com. This page contains the latest information.
What is the target group? Who are users?
AuxUtils library intended for designed and developers of the software applications that have some restriction or limitation at Boost functionality, which AuxUtils is eliminated.
Is the AuxUtils thread-safe?
Yes. The AuxUtils library was designed as thread safe library until you are using thread safe STL implementation.
All unit tests dont' pass.
On some operation system shared memory test may fail due to operation system configuration. Read section about shared memory in detail and check how to configure you operation system shared memory relative options.
To see the latest list of the roadmap please visit the Roadmap page at www.majoron.com. This page contain the latest information.
Follow notation is used at change log. Each entry begin with a version, for which entry for created. Then follow component at {}. Then follow category of the bug at []. It can be bug report, feature request and etc. Than follow bug number at bug tracking system between // signs. And then follow a description of the entry. For example entry 1.0 { AntHill Core } [ Feature Request ] / 380 / STLport support mean than entry was created for 1.0 version of the AntHill Core component and entry is feature request with 380 number at bug tracking system to support STLPort library.
1.0 { AuxUtils Core } [ Feature Request ] / 523 / Add a keyword to print usage and view all included unit test
1.0 { AuxUtils Core } [ Feature Request ] / 530 / Build library with manifist (configure vcprojects).
1.0 { AuxUtils Core } [ Feature Request ] / 599 / Add STLPort support (--wih-stlport key at autoconf)
1.0 { Documentation } [ Feature Request ] / 369 / Add UML sequence diagram
1.0 { Documentation } [ Feature Request ] / 472 / Add information to building section about 3rdparty downloads
1.0 { Documentation } [ Feature Request ] / 486 / Write to documentation and site about how to dowload pecomiled library
1.0 { Documentation } [ Feature Request ] / 535 / Write to documentation about minifiest (not embedded).
1.0 { Setup } [ Configuration Request ] / 260 / Include eclipse projects to installation
1.0 { Setup } [ Configuration Request ] / 336 / Add a different type of the build for 32 & 64 bit based on ant script resolution
To see the latest list of the change log please visit the Change Log page at www.majoron.com. This page contain the latest information.
Follow notation is used at change log. Each entry begin with a version, for which entry for created. Then follow component at {}. Then follow category of the bug at []. It can be bug report, feature request and etc. Than follow bug number at bug tracking system between // signs. And then follow a description of the entry. For example empty 1.0 { AntHill Core } [ Feature Request ] / 380 / STLport support mean than entry was created for 1.0 version of the AntHill Core component and empty is feature request with 380 number at bug tracking system to support STLPort library.
1.0 { AuxUtils Core } [ Bug Report ] / 556 / Inclide include, erase it
1.0 { Documentation } [ Bug Report ] / 674 / Up Installation layouts menu at one level
1.0 { Setup } [ Bug Report ] / 540 / Snpippets not included to msvc8 & autoconf porject
1.0 { AuxUtils Core } [ Configuration Request ] / 635 / Print dump 0F 0E rather than f e
1.0 { AuxUtils Core } [ Configuration Request ] / 208 / Add support a projects files for msvc 6,7 & 9
1.0 { AuxUtils Core } [ Feature Request ] / 687 / Support unicode
1.0 { AuxUtils Core } [ Feature Request ] / 634 / Add a include file iomanip
1.0 { AuxUtils Core } [ Feature Request ] / 504 / Add a methods to write and read dump buffer to string and from stream
1.0 { Documentation } [ Feature Request ] / 522 / Add a section how to execute single unit test, stress test and view all unit tests
0.5 { AuxUtils Core } [ --- ] / 228 / SharedMutex & SharedSemapore OS specifics or invalid usage or bug
0.5 { AuxUtils Core } [ --- ] / 227 / GetLastError for Unix-like implementation
0.5 { AuxUtils Core } [ --- ] / 206 / Extend of the ByteBuffer Interface
0.5 { AuxUtils Core } [ --- ] / 205 / SequenceGenerator consistent state
0.5 { AuxUtils Core } [ --- ] / 204 / Setup isBounded for Sequence generator
0.5 { AuxUtils Core } [ --- ] / 193 / Memory leak(?)
0.5 { AuxUtils Core } [ --- ] / 169 / Create constructor for ByteBuffer
0.5 { AuxUtils Core } [ --- ] / 163 / change license from majoron to latestbit.
0.5 { AuxUtils Core } [ --- ] / 162 / Add resource with version for win32 for all libraries
0.5 { AuxUtils Core } [ --- ] / 160 / Add constructor to ByteBuffer
0.5 { AuxUtils Core } [ --- ] / 158 / Add default value of the owner for shared mutex
0.5 { Documentation } [ --- ] / 251 / Write documentation (pdf by docbook?)
0.5 { Setup } [ --- ] / 250 / Include documentation to distributioin package.
0.5 { Setup } [ --- ] / 225 / UnitTest conflicts.
0.5 { Setup } [ --- ] / 222 / make install destination includes files
0.5 { Setup } [ --- ] / 156 / Support STLPort library.
0.5 { Setup } [ --- ] / 153 / create automake & autoconf installation for linux
This appendix contains lists the developers, contributors, and supporters that have helped to make AuxUtils what it is today.
The following people have created AuxUtils.
Abdulla Abdurakhmanov Lead developer and main author of the AuxUtils. The main ideas and the first version of the library was created by Abdulla Abdurakhmanov
Artem Rufanov Lead developer of the AuxUtils. He is support the library and responsible for future development and adjusting to requirement for AntHill and other libraries which were and will be create by Majoron.
The following people have helped as to do AuxUtils better.
You can be here.
The following people have helped as to write documentation for AuxUtils.
Artem Rufanov. Main write of the AuxUtils manual.
Roman Rufanov Active contributor to the AuxUtils manual.
AuxUtils is a tiny library but meantime it is using other open source libraries. The following is a list of some of the libraries we have used to create AuxUtils. We use this to express our thanks to those that has created them as without these we could not have made AuxUtils what it is today.
Boost From whom we got an excellent boost library.
The following is a list of some of the tools we have used to create AuxUtils. We use this to express our thanks to those that has created them as without these we could not have made AuxUtils what it is today.
Free Software Foundation From whom we got an excellent compiler (gcc), an excellent debugger (gdb).
Doxygen This development tools allow to create documentation for C++. It is used to create a well-formated html API documentation.
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.