Quick Start Guide for Amino C++ Components

Using Amino C++ Template Library

Building Process

Amino Cpp is a header-only library like STL, which makes it very easy to setup. Only two steps should be executed:
  1. Run bash script under bin/select_platform.sh and select the right platform
  2. Copy the include directory to somewhere you preferred and use -I option to tell gcc or xlc to find it.

Examples

Following is an example which shows how to use Amino Template Library in a common C++ program.

More examples...

#include <iostream>

#include <amino/stack.h>

using�namespace�amino;

int�main(int�argc, char�* argv[]){
����LockFreeStack<int> stack1;

����stack1.push(5);

����int�res;
����if(stack1.pop(res)){
��������std::cout<<res<<std::endl;
����}

����return�0;
}

Yes, the amino library is as simple as STL. And above sample involves nothing about parallel or thread. This is intentional since we want to show how simple it is at first. Now let's dive a little more and see a case where multiple threads operate on one stack.

#include <iostream>

#include <amino/thread.h>
#include <amino/stack.h>

using�namespace�amino;

LockFreeStack<int> stack1;

class�PushOp{
����public:
��������void�operator()(){
������������for(int�i=0;i<1000;i++)
����������������stack1.push(i);
��������}
};

class�PopOp{
����public:
��������void�operator()(){
������������for(int�i=999;i>=0;i--){
����������������int�res;
����������������while( !stack1.pop(res) )
����������������{}

����������������if(res != i){
��������������������cout<<"Res: "<<res<<" I: "<<i<<"\n";
��������������������throw�std::logic_error("Output is not correct!\n");
����������������}
������������}
��������}
};

int�main(int�argc, char�* argv[]){
����PushOp op1;
����PopOp op2;
����Thread thread1(op1), thread2(op2);

����thread1.join();
����thread2.join();

����return�0;
}

Above program will prodce no output if our lock-free stack work correctly. If we save above two files to "stack_st.cpp" and "stack_mt.cpp", we'll be able to compile above two programs with following Makefile:

all:stack_st stack_mt

stack_st:stack_st.cpp
����g++ -I../include -o stack_st -lpthread stack_st.cpp��

stack_mt:stack_mt.cpp
����g++ -I../include -o stack_mt -lpthread stack_mt.cpp��

clean:
����rm -rf stack_st stack_mt

And you don't need to type them from scratch by yourself. The source code and Makefile are contained in the <AMINO-ROOT>/examples directory

You can get more examples here.

SMR is used for memory management

This section is only for develpers who want to know internal mechanism of this library. For lock-free components like Stack, a mechanism to manage memory is necessary. The traditional "Who malloc, who free" principle is not applicable for multi-threaded application, since you never know if other threads are still using that piece of memory. GC since a perfect approach for managing this problem. The problem is that C++ doesn't have standard garbage collector. Obviously, we need a way to manage memory for our lock-free components. There are multiple choices here. And we used SMR from Maged Michael to manage memory. Pleae refer the algorithm from: http:://www.research.ibm.com/people/m/michael/ieeetpds-2004.pdf

Try Amino Test Case

Amino project comes with various test case, you can invoke the test case and verify correctness with following command:

cd <AMINO-ROOT>/test

make check

Using Amino C Library

Lock-free Allocator

Notes on use of lock-free allocator (CLFMalloc):

How to Use Lock-Free Malloc/Free

The lock-free allocator can be compiled to a shared library on linux system. For a program to use CLFMalloc, it can be linked explicitly with the clfmalloc library. On some systems (such as Linux) calls to malloc functions can be interposed by setting the variable LD_PRELOAD to the clfmalloc library without need for replacing the default malloc library or relinking.

Environment variables

The allocator checks one environment variable CLFMALLOC_NUMHEAPS. If the value is valid (i.e., an integer between 1 and 512), the number of heaps is set to the smallest power of 2 greater than or equal to the value. If the variable is undefined or its value is non-integer or out of the range 1..512, a default value of 64 is used. Unpopulated heaps occupy only 1 KB. The maximum size of a populated heap is in the order of 1 MB. Typically, the average size of a populated heap is less than 100 KB. In general it is good for latency and scalability to have the number of heaps about 4 times the number of hardware threads.

Supported functions

CLFMalloc supports the standard allocation functions malloc, free, calloc, and realloc.

Reference

Maged M. Michael, Scalable Lock-Free Dynamic Memory Allocation, The 2004 ACM SIGPLAN Conference on Programming Language Design and Implementation (PLDI), pages 35-46, June 2004.

Software Transactional Memory Library

Amino provides a software transactional memory library, which can be used with an extended version of IBM XLC http://www.alphaworks.ibm.com/tech/xlcstm/. Please refer stm document for more detailed information.

Next Step