User Guide/Introduction

Getting Started

Obtaining The Library

The library is downloadable from the homepage, as given in index.html in this documentation. The URLs are kept in one page (to make changing them easier!). There should be a choice of source tar.gz , tar.bz2 or zip files.

Configuring The Library At Compile-Time

The file csp/csp_config.h contains several defines controlling the behaviour of the library. It is auto-generating by make under Un*x systems, so it will not be there unless you have compiled the library at least once. By default it contains (at time of writing):

	#define UNIX
	#define CPPCSP_USING_DEFAULT_SCHEDULER
	

The first line defines the operating system it will be compiled on. UNIX should soon be renamed POSIX. Currently only that or WIN32 is supported -- one and only one of these should be defined. Picking the wrong one will cause lots of errors which is handy...

The second line tells the library to use the default scheduler.

Todo:

discuss this in further detail

This is pretty rubbish as intros go - do something about it!

Compiling/Installing The Library

Compiling under Linux and Unix variants is a matter of using the GNU standard commands:

	./configure && make && make install
	

Compiling under Windows can be done using the MSYS system provided with MINGW. This is the simplest way of compiling it, but alternatively any other standards-compliant compiler should work, just by putting all the source files in the csp/ source directory into a static library project (a long story, but under Windows, the library seems to have to be static) and compiling. Please let me know of your successes/failures with various compilers.

Using The Library

Programs wanting to use with the library should link with cppcsp.lib / libcppcsp.a / libcppcsp.la as appropriate and have the following line in their code:

	#include <csp/csp.h>
	

This line is the only include directive that is required. The program should also have the function calls:

	Start_CSP();
	//...All code that uses the C++CSP library
	End_CSP():
	

around all code that uses the library, as indicated.

My First C++CSP Program

Now we will look at example code for using the library. The common way of doing things in these docs is to show code first, then explain so here it is (ripped from the test suite and tidied up):

    #include <csp/csp.h>

    using namespace csp;

    class OneIOneO : public CSProcess
    {
        Chanin<int>     in;
        Chanout<int>    out;
        int             id;

    protected:
        void run()
        {
            int n;

            in >> n;	//The process does one input...

            out << id;	//then one output
        };
    public:
        OneIOneO(const Chanin<int>& i,const Chanout<int>& o,int n)
            :   CSProcess(65536),in(i),out(o),id(n)
        {
        };
    };

    class OneOOneI : public CSProcess
    {
        Chanin<int>     in;
        Chanout<int>    out;
        int             id;

    protected:
        void run()
        {
    	    int n;

    	    out << id;	//The process does an output

            in >> n;	//Then an input
        };
    public:
    	OneOOneI(const Chanin<int>& i,const Chanout<int>& o,int n)
        	:   CSProcess(65536),in(i),out(o),id(n)
	    {
    	};
	};	
	

There's a lot to take in but its fairly simple. The first line includes the one necessary header file, and then the next line says to use the namespace csp.

Then we declare out first process, "OneIOneO", a (public) child of CSProcess, the main process class. It has three data members -- a reading end (Chanin) of a channel of integers, a writing end (Chanout) of a channel of integers, and an integer id.

Its functionality is specified in its (protected) void run() method that implements the pure virtual method from CSProcess.

The line in >> n; line takes an input from the channel of which in is an end (or to put in simpler, the channel in though this is a slight misnomer) into the integer variable n;

Similarly, the line out << id; outputs (also referred to as writes) the integer id onto the channel out.

The constructor is passed these two channel ends which it uses to initialise its members with via copy constructors. Channel ends can be copy constructed and assigned all you want, it is up to the user of the library to ensure they are used properly (see later sections about shared channels).

The constructor also passes a mysterious number to the CSProcess constructor. This value is the stack size for the process. It is unfortunate but necessary that the user has to specify this number. I recommend a minimum of 64 kilobytes unless you really know what you are doing, and up to a megabyte for complex processes. Later sections will deal with this in more detail.

Once you understand the first process, the second one is straightforward as it is a mirror of the first.

The code to actually utilise these processes is here:

---