libppl(3)							  libppl overview							 libppl(3)

NAME

       libppl - the C++ interface of the Parma Polyhedra Library

SYNOPSIS

       #include <ppl.hh>

       c++ file.cc -lppl

DESCRIPTION

       This  is  a  short overview on how to use the Parma Polyhedra Library (PPL) in your C++ programs on Unix-like operating systems.  Note that
       the PPL has interfaces also for C, Java, OCaml and a number of Prolog systems: look elsewhere for documentation on those.  Note	also  that
       the present document does not describe the library functionality, its classes or its methods and functions: see The Parma Polyhedra Library
       User's Manual (version 0.11.2) for this kind of information.

INCLUDING THE HEADER FILE

       The C++ interface of the PPL has only one header file, named ppl.hh.  So your program should contain a directive of the form

       #include <ppl.hh>

       Of course, you must make sure you installed the PPL in a place where the compiler can find it, either by itself or with the help of a suit-
       able  -Idir  command line option (see the file INSTALL for information on how to configure the library so that it is installed in the place
       of your choice).

INITIALIZING AND FINALIZING THE LIBRARY

       The mere inclusion of ppl.hh in at least one file of your project will cause the automatic initialization and finalization of the  library.
       However,  there	are  situations in which automatic initialization and finalization is not desirable (e.g., if the application fiddles with
       the GMP's memory allocation functions).	In those cases, every inclusion of ppl.hh must take the form

       #define PPL_NO_AUTOMATIC_INITIALIZATION
       #include <ppl.hh>

       When automatic initialization and finalization is disabled you must absolutely call the function

       void Parma_Polyhedra_Library::initialize()

       before using the library.  It is also a good norm to call the function

       void Parma_Polyhedra_Library::finalize()

       when you are done with the library.

USING THE LIBRARY

       Keeping in mind that there is no substitute for a careful reading of The Parma Polyhedra Library User's Manual (version	0.11.2),  you  can
       find many examples of use in the directories tests (see the README file in that directory) and demos/ppl_lcdd of the source distribution.

LINKING WITH THE LIBRARY

       Linking	with  the  C++	interface of the Parma Polyhedra Library is best done using the C++ compiler itself: usually, specifying the -lppl
       command line option is enough.  In fact, if you use a shared version of the library, this automatically records the dependency from the GMP
       library,  something  that  the  linker  ought  to  deal with gracefully.  Otherwise you will have to add -lgmpxx -lgmp to the command line.
       Things are more complex if you installed the PPL into some nonstandard place.  In this case you will have to use the -Ldir option  and,	if
       you  use  a  shared  version of the library, possible take further steps: see the documentation of your system for more information on this
       subject (the Program Library HOWTO is especially valuable for GNU/Linux users).

IMPLEMENTING MEMORY-GUARDED COMPUTATIONS
       One of the interesting features of the Parma Polyhedra Library is the possibility to implement memory-guarded computations.   The  idea	is
       that you can limit the amount of virtual memory available to the process, launch a PPL computation, and be ready to catch an std::bad_alloc
       exception.  Since the library is exception-safe, you can take the appropriate corrective measures  (e.g.,  simplify  the  polyhedra  and/or
       select  less precise though less complex algorithms), and restart the computation.  In order to do that, you should define alternative mem-
       ory allocation functions for GMP that throw std::bad_alloc upon memory exhaustion.  For instance:

       #include <new>
       #include <cstdlib>

       extern "C" void*
       cxx_malloc(size_t size) {
	 void* p = malloc(size);
	 if (p != 0 || size == 0)
	   return p;

	 throw std::bad_alloc();
       }

       extern "C" void*
       cxx_realloc(void* q, size_t, size_t new_size) {
	 void* p = realloc(q, new_size);
	 if (p != 0 || new_size == 0)
	   return p;

	 throw std::bad_alloc();
       }

       extern "C" void
       cxx_free(void* p, size_t) {
	 free(p);
       }

       Then you must install these functions and this can be done in two different ways:

       (1)    If your C++ compiler supports __attribute__ ((weak)) and you do not have any other special needs, then you can simply link  to  your
	      application a C function ppl_set_GMP_memory_allocation_functions(void) such as

	      extern "C" void
	      ppl_set_GMP_memory_allocation_functions(void) {
		mp_set_memory_functions(cxx_malloc, cxx_realloc, cxx_free);
	      }

	      This is all that you have to do, whether or not you use the automatic initialization feature of the library (see above): in any case
	      the initialization procedure will automatically call ppl_set_GMP_memory_allocation_functions(void).

       (2)    If your C++ compiler does not support __attribute__ ((weak)) then you cannot use the automatic initialization feature of the library
	      (see above) and should write a main program of the form

	      int main() {
		// The ordering of the following function calls is important.
		mp_set_memory_functions(cxx_malloc, cxx_realloc, cxx_free);
		Parma_Polyhedra_Library::initialize();
		...

USING NATIVE FLOATING POINT NUMBERS

       At  initialization  time, the Parma Polyhedra Library sets the FPU rounding mode in a way that allows its floating-point-based computations
       to be conservative (i.e., possibly approximated but correct) and reasonably efficient.  In case your application itself uses native  float-
       ing  point  numbers  and  relies  on a particular rounding mode (if you are in doubt, assume that it does rely on round-to-nearest to be in
       effect), you should use the function

       void Parma_Polyhedra_Library::restore_pre_PPL_rounding()

       after the PPL initialization and before using native floating point numbers in the application.	If  your  application  does  not  use  any
       floating-point-based PPL abstraction, no further measure should be taken.  Otherwise, it is imperative to call the function

       void Parma_Polyhedra_Library::set_rounding_for_PPL()

       before invoking any PPL interface related to such abstractions.

SEE ALSO

       ppl-config(1)

       Roberto	Bagnara, Patricia M. Hill, and Enea Zaffanella.  The Parma Polyhedra Library User's Manual (version 0.11.2), available (in several
       formats) at http://www.cs.unipr.it/ppl/ .

       David A. Wheeler.  Program Library HOWTO, available (in several formats) at http://www.dwheeler.com/program-library/ .

AVAILABILITY

       The latest version of the Parma Polyhedra Library and all the documentation is available at http://www.cs.unipr.it/ppl/ .

AUTHOR

       See the file CREDITS in the source distribution or use the command ppl-config --credits for a list of contributors.

REPORTING BUGS

       Report bugs to <ppl-devel@cs.unipr.it>.

COPYRIGHT

       Copyright (C) 2001-2010 Roberto Bagnara <bagnara@cs.unipr.it> Copyright (C) 2010-2011 BUGSENG srl (http://bugseng.com)
       This is free software; see the file COPYING in the source distribution or use the command ppl-config --copying to obtain the copying condi-
       tions.  There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

PPL 0.11.2							   February 2011							 libppl(3)