1libppl(3) libppl overview libppl(3)
2
6 libppl - the C++ interface of the Parma Polyhedra Library
7
9 #include <ppl.hh>
10 c++ file.cc -lppl
12
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
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 #include <ppl.hh>
29 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
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 #define PPL_NO_AUTOMATIC_INITIALIZATION
46 #include <ppl.hh>
47 When automatic initialization and finalization is disabled you must
49 absolutely call the function
50 void Parma_Polyhedra_Library::initialize()
52 before using the library. It is also a good norm to call the function
54 void Parma_Polyhedra_Library::finalize()
56 when you are done with the library.
58
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
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
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 #include <new>
94 #include <cstdlib>
95 extern "C" void*
97 cxx_malloc(size_t size) {
98 void* p = malloc(size);
99 if (p != 0 || size == 0)
100 return p;
101 throw std::bad_alloc();
103 }
104 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 throw std::bad_alloc();
112 }
113 extern "C" void
115 cxx_free(void* p, size_t) {
116 free(p);
117 }
118 Then you must install these functions and this can be done in two dif‐
120 ferent ways:
121 (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 extern "C" void
128 ppl_set_GMP_memory_allocation_functions(void) {
129 mp_set_memory_functions(cxx_malloc, cxx_realloc, cxx_free);
130 }
131 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 (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 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
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 void Parma_Polyhedra_Library::restore_pre_PPL_rounding()
159 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 void Parma_Polyhedra_Library::set_rounding_for_PPL()
166 before invoking any PPL interface related to such abstractions.
168
172 ppl-config(1)
173 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 David A. Wheeler. Program Library HOWTO, available (in several for‐
179 mats) at http://www.dwheeler.com/program-library/ .
180
183 The latest version of the Parma Polyhedra Library and all the documen‐
184 tation is available at http://bugseng.com/products/ppl/ .
185
188 See the file CREDITS in the source distribution or use the command
189 ppl-config --credits for a list of contributors.
190
193 Report bugs to <ppl-devel@cs.unipr.it>.
194
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.
203PPL 1.2 February 2016 libppl(3)