1libppl(3)                       libppl overview                      libppl(3)
2
3
4

NAME

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

SYNOPSIS

9       #include <ppl.hh>
10
11       c++ file.cc -lppl
12
13

DESCRIPTION

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

INCLUDING THE HEADER FILE

25       The  C++  interface  of the PPL has only one header file, named ppl.hh.
26       So your program should contain a directive of the form
27
28       #include <ppl.hh>
29
30       Of course, you must make sure you installed the PPL in  a  place  where
31       the  compiler can find it, either by itself or with the help of a suit‐
32       able -Idir command line option (see the file INSTALL for information on
33       how  to  configure  the library so that it is installed in the place of
34       your choice).
35
36

INITIALIZING AND FINALIZING THE LIBRARY

38       The mere inclusion of ppl.hh in at least one file of your project  will
39       cause  the  automatic  initialization  and finalization of the library.
40       However, there are situations in  which  automatic  initialization  and
41       finalization  is  not  desirable (e.g., if the application fiddles with
42       the GMP's memory allocation functions).  In those cases,  every  inclu‐
43       sion of ppl.hh must take the form
44
45       #define PPL_NO_AUTOMATIC_INITIALIZATION
46       #include <ppl.hh>
47
48       When  automatic  initialization  and  finalization is disabled you must
49       absolutely call the function
50
51       void Parma_Polyhedra_Library::initialize()
52
53       before using the library.  It is also a good norm to call the function
54
55       void Parma_Polyhedra_Library::finalize()
56
57       when you are done with the library.
58
59

USING THE LIBRARY

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

LINKING WITH THE LIBRARY

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

IMPLEMENTING MEMORY-GUARDED COMPUTATIONS

82       One  of  the interesting features of the Parma Polyhedra Library is the
83       possibility to implement memory-guarded computations.  The idea is that
84       you  can  limit  the amount of virtual memory available to the process,
85       launch a PPL computation, and  be  ready  to  catch  an  std::bad_alloc
86       exception.   Since  the  library  is  exception-safe,  you can take the
87       appropriate corrective measures (e.g., simplify  the  polyhedra  and/or
88       select  less  precise  though less complex algorithms), and restart the
89       computation.  In order to do that, you should define alternative memory
90       allocation  functions  for  GMP  that  throw std::bad_alloc upon memory
91       exhaustion.  For instance:
92
93       #include <new>
94       #include <cstdlib>
95
96       extern "C" void*
97       cxx_malloc(size_t size) {
98         void* p = malloc(size);
99         if (p != 0 || size == 0)
100           return p;
101
102         throw std::bad_alloc();
103       }
104
105       extern "C" void*
106       cxx_realloc(void* q, size_t, size_t new_size) {
107         void* p = realloc(q, new_size);
108         if (p != 0 || new_size == 0)
109           return p;
110
111         throw std::bad_alloc();
112       }
113
114       extern "C" void
115       cxx_free(void* p, size_t) {
116         free(p);
117       }
118
119       Then you must install these functions and this can be done in two  dif‐
120       ferent ways:
121
122       (1)    If  your C++ compiler supports __attribute__ ((weak)) and you do
123              not have any other special needs, then you can  simply  link  to
124              your   application   a   C  function  ppl_set_GMP_memory_alloca‐
125              tion_functions(void) such as
126
127              extern "C" void
128              ppl_set_GMP_memory_allocation_functions(void) {
129                mp_set_memory_functions(cxx_malloc, cxx_realloc, cxx_free);
130              }
131
132              This is all that you have to do, whether  or  not  you  use  the
133              automatic  initialization feature of the library (see above): in
134              any case the initialization procedure  will  automatically  call
135              ppl_set_GMP_memory_allocation_functions(void).
136
137       (2)    If  your  C++  compiler  does not support __attribute__ ((weak))
138              then you cannot use the automatic initialization feature of  the
139              library (see above) and should write a main program of the form
140
141              int main() {
142                // The ordering of the following function calls is important.
143                mp_set_memory_functions(cxx_malloc, cxx_realloc, cxx_free);
144                Parma_Polyhedra_Library::initialize();
145                ...
146
147
148

USING NATIVE FLOATING POINT NUMBERS

150       At initialization time, the Parma Polyhedra Library sets the FPU round‐
151       ing mode in a way that allows its floating-point-based computations  to
152       be  conservative  (i.e., possibly approximated but correct) and reason‐
153       ably efficient.  In case your application itself uses  native  floating
154       point  numbers  and relies on a particular rounding mode (if you are in
155       doubt, assume that it does rely on round-to-nearest to be  in  effect),
156       you should use the function
157
158       void Parma_Polyhedra_Library::restore_pre_PPL_rounding()
159
160       after  the  PPL  initialization  and before using native floating point
161       numbers in the application.  If  your  application  does  not  use  any
162       floating-point-based  PPL  abstraction,  no  further  measure should be
163       taken.  Otherwise, it is imperative to call the function
164
165       void Parma_Polyhedra_Library::set_rounding_for_PPL()
166
167       before invoking any PPL interface related to such abstractions.
168
169
170

SEE ALSO

172       ppl-config(1)
173
174       Roberto Bagnara, Patricia M. Hill,  and  Enea  Zaffanella.   The  Parma
175       Polyhedra  Library  User's  Manual (version 1.2), available (in several
176       formats) at http://bugseng.com/products/ppl/ .
177
178       David A. Wheeler.  Program Library HOWTO, available  (in  several  for‐
179       mats) at http://www.dwheeler.com/program-library/ .
180
181

AVAILABILITY

183       The  latest version of the Parma Polyhedra Library and all the documen‐
184       tation is available at http://bugseng.com/products/ppl/ .
185
186

AUTHOR

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

REPORTING BUGS

193       Report bugs to <ppl-devel@cs.unipr.it>.
194
195
197       Copyright (C) 2001-2010 Roberto Bagnara <bagnara@cs.unipr.it> Copyright
198       (C) 2010-2016 BUGSENG srl (http://bugseng.com)
199       This is free software; see the file COPYING in the source  distribution
200       or  use  the  command ppl-config --copying to obtain the copying condi‐
201       tions.  There is NO warranty; not even for MERCHANTABILITY  or  FITNESS
202       FOR A PARTICULAR PURPOSE.
203
204
205
206PPL 1.2                          February 2016                       libppl(3)
Impressum