Provided by: libppl-dev_1.2-8.1build5_amd64 bug

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 1.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 1.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     1.2),     available    (in    several    formats)    at
       http://bugseng.com/products/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://bugseng.com/products/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 AND NO WARRANTY

       Copyright  (C)  2001-2010  Roberto  Bagnara  <bagnara@cs.unipr.it> Copyright (C) 2010-2016
       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 conditions.  There is NO warranty; not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.