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.10.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
suitable -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.10.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 memory
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 floating 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.10.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-2009 Roberto Bagnara <bagnara@cs.unipr.it>
This is free software; see the file COPYING in the source distribution
or use the command ppl-config --copying to obtain the copying
conditions. There is NO warranty; not even for MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.