| blob | 6fc407df0d68ca27d4473008f08adba3108bf46e |
1 ===============
2 Support Library
3 ===============
5 Abstract
6 ========
8 This document provides some details on LLVM's Support Library, located in the
9 source at ``lib/Support`` and ``include/llvm/Support``. The library's purpose
10 is to shield LLVM from the differences between operating systems for the few
11 services LLVM needs from the operating system. Much of LLVM is written using
12 portability features of standard C++. However, in a few areas, system dependent
13 facilities are needed and the Support Library is the wrapper around those
14 system calls.
16 By centralizing LLVM's use of operating system interfaces, we make it possible
17 for the LLVM tool chain and runtime libraries to be more easily ported to new
18 platforms since (theoretically) only ``lib/Support`` needs to be ported. This
19 library also unclutters the rest of LLVM from #ifdef use and special cases for
20 specific operating systems. Such uses are replaced with simple calls to the
21 interfaces provided in ``include/llvm/Support``.
23 Note that the Support Library is not intended to be a complete operating system
24 wrapper (such as the Adaptive Communications Environment (ACE) or Apache
25 Portable Runtime (APR)), but only provides the functionality necessary to
26 support LLVM.
28 The Support Library was originally referred to as the System Library, written
29 by Reid Spencer who formulated the design based on similar work originating
30 from the eXtensible Programming System (XPS). Several people helped with the
31 effort; especially, Jeff Cohen and Henrik Bach on the Win32 port.
33 Keeping LLVM Portable
34 =====================
36 In order to keep LLVM portable, LLVM developers should adhere to a set of
37 portability rules associated with the Support Library. Adherence to these rules
38 should help the Support Library achieve its goal of shielding LLVM from the
39 variations in operating system interfaces and doing so efficiently. The
40 following sections define the rules needed to fulfill this objective.
42 Don't Include System Headers
43 ----------------------------
45 Except in ``lib/Support``, no LLVM source code should directly ``#include`` a
46 system header. Care has been taken to remove all such ``#includes`` from LLVM
47 while ``lib/Support`` was being developed. Specifically this means that header
48 files like "``unistd.h``", "``windows.h``", "``stdio.h``", and "``string.h``"
49 are forbidden to be included by LLVM source code outside the implementation of
50 ``lib/Support``.
52 To obtain system-dependent functionality, existing interfaces to the system
53 found in ``include/llvm/Support`` should be used. If an appropriate interface is
54 not available, it should be added to ``include/llvm/Support`` and implemented in
55 ``lib/Support`` for all supported platforms.
57 Don't Expose System Headers
58 ---------------------------
60 The Support Library must shield LLVM from **all** system headers. To obtain
61 system level functionality, LLVM source must
62 ``#include "llvm/Support/Thing.h"`` and nothing else. This means that
63 ``Thing.h`` cannot expose any system header files. This protects LLVM from
64 accidentally using system specific functionality and only allows it via
65 the ``lib/Support`` interface.
67 Use Standard C Headers
68 ----------------------
70 The **standard** C headers (the ones beginning with "c") are allowed to be
71 exposed through the ``lib/Support`` interface. These headers and the things they
72 declare are considered to be platform agnostic. LLVM source files may include
73 them directly or obtain their inclusion through ``lib/Support`` interfaces.
75 Use Standard C++ Headers
76 ------------------------
78 The **standard** C++ headers from the standard C++ library and standard
79 template library may be exposed through the ``lib/Support`` interface. These
80 headers and the things they declare are considered to be platform agnostic.
81 LLVM source files may include them or obtain their inclusion through
82 ``lib/Support`` interfaces.
84 High Level Interface
85 --------------------
87 The entry points specified in the interface of ``lib/Support`` must be aimed at
88 completing some reasonably high level task needed by LLVM. We do not want to
89 simply wrap each operating system call. It would be preferable to wrap several
90 operating system calls that are always used in conjunction with one another by
91 LLVM.
93 For example, consider what is needed to execute a program, wait for it to
94 complete, and return its result code. On Unix, this involves the following
95 operating system calls: ``getenv``, ``fork``, ``execve``, and ``wait``. The
96 correct thing for ``lib/Support`` to provide is a function, say
97 ``ExecuteProgramAndWait``, that implements the functionality completely. what
98 we don't want is wrappers for the operating system calls involved.
100 There must **not** be a one-to-one relationship between operating system
101 calls and the Support library's interface. Any such interface function will be
102 suspicious.
104 No Unused Functionality
105 -----------------------
107 There must be no functionality specified in the interface of ``lib/Support``
108 that isn't actually used by LLVM. We're not writing a general purpose operating
109 system wrapper here, just enough to satisfy LLVM's needs. And, LLVM doesn't
110 need much. This design goal aims to keep the ``lib/Support`` interface small and
111 understandable which should foster its actual use and adoption.
113 No Duplicate Implementations
114 ----------------------------
116 The implementation of a function for a given platform must be written exactly
117 once. This implies that it must be possible to apply a function's
118 implementation to multiple operating systems if those operating systems can
119 share the same implementation. This rule applies to the set of operating
120 systems supported for a given class of operating system (e.g. Unix, Win32).
122 No Virtual Methods
123 ------------------
125 The Support Library interfaces can be called quite frequently by LLVM. In order
126 to make those calls as efficient as possible, we discourage the use of virtual
127 methods. There is no need to use inheritance for implementation differences, it
128 just adds complexity. The ``#include`` mechanism works just fine.
130 No Exposed Functions
131 --------------------
133 Any functions defined by system libraries (i.e. not defined by ``lib/Support``)
134 must not be exposed through the ``lib/Support`` interface, even if the header
135 file for that function is not exposed. This prevents inadvertent use of system
136 specific functionality.
138 For example, the ``stat`` system call is notorious for having variations in the
139 data it provides. ``lib/Support`` must not declare ``stat`` nor allow it to be
140 declared. Instead it should provide its own interface to discovering
141 information about files and directories. Those interfaces may be implemented in
142 terms of ``stat`` but that is strictly an implementation detail. The interface
143 provided by the Support Library must be implemented on all platforms (even
144 those without ``stat``).
146 No Exposed Data
147 ---------------
149 Any data defined by system libraries (i.e. not defined by ``lib/Support``) must
150 not be exposed through the ``lib/Support`` interface, even if the header file
151 for that function is not exposed. As with functions, this prevents inadvertent
152 use of data that might not exist on all platforms.
154 Minimize Soft Errors
155 --------------------
157 Operating system interfaces will generally provide error results for every
158 little thing that could go wrong. In almost all cases, you can divide these
159 error results into two groups: normal/good/soft and abnormal/bad/hard. That is,
160 some of the errors are simply information like "file not found", "insufficient
161 privileges", etc. while other errors are much harder like "out of space", "bad
162 disk sector", or "system call interrupted". We'll call the first group "*soft*"
163 errors and the second group "*hard*" errors.
165 ``lib/Support`` must always attempt to minimize soft errors. This is a design
166 requirement because the minimization of soft errors can affect the granularity
167 and the nature of the interface. In general, if you find that you're wanting to
168 throw soft errors, you must review the granularity of the interface because it
169 is likely you're trying to implement something that is too low level. The rule
170 of thumb is to provide interface functions that **can't** fail, except when
171 faced with hard errors.
173 For a trivial example, suppose we wanted to add an "``OpenFileForWriting``"
174 function. For many operating systems, if the file doesn't exist, attempting to
175 open the file will produce an error. However, ``lib/Support`` should not simply
176 throw that error if it occurs because its a soft error. The problem is that the
177 interface function, ``OpenFileForWriting`` is too low level. It should be
178 ``OpenOrCreateFileForWriting``. In the case of the soft "doesn't exist" error,
179 this function would just create it and then open it for writing.
181 This design principle needs to be maintained in ``lib/Support`` because it
182 avoids the propagation of soft error handling throughout the rest of LLVM.
183 Hard errors will generally just cause a termination for an LLVM tool so don't
184 be bashful about throwing them.
186 Rules of thumb:
188 #. Don't throw soft errors, only hard errors.
190 #. If you're tempted to throw a soft error, re-think the interface.
192 #. Handle internally the most common normal/good/soft error conditions
193 so the rest of LLVM doesn't have to.
195 No throw Specifications
196 -----------------------
198 None of the ``lib/Support`` interface functions may be declared with C++
199 ``throw()`` specifications on them. This requirement makes sure that the
200 compiler does not insert additional exception handling code into the interface
201 functions. This is a performance consideration: ``lib/Support`` functions are
202 at the bottom of many call chains and as such can be frequently called. We
203 need them to be as efficient as possible. However, no routines in the system
204 library should actually throw exceptions.
206 Code Organization
207 -----------------
209 Implementations of the Support Library interface are separated by their general
210 class of operating system. Currently only Unix and Win32 classes are defined
211 but more could be added for other operating system classifications. To
212 distinguish which implementation to compile, the code in ``lib/Support`` uses
213 the ``LLVM_ON_UNIX`` and ``_WIN32`` ``#defines``. Each source file in
214 ``lib/Support``, after implementing the generic (operating system independent)
215 functionality needs to include the correct implementation using a set of
216 ``#if defined(LLVM_ON_XYZ)`` directives. For example, if we had
217 ``lib/Support/Path.cpp``, we'd expect to see in that file:
219 .. code-block:: c++
221 #if defined(LLVM_ON_UNIX)
222 #include "Unix/Path.inc"
223 #endif
224 #if defined(_WIN32)
225 #include "Windows/Path.inc"
226 #endif
228 The implementation in ``lib/Support/Unix/Path.inc`` should handle all Unix
229 variants. The implementation in ``lib/Support/Windows/Path.inc`` should handle
230 all Windows variants. What this does is quickly inc the basic class
231 of operating system that will provide the implementation. The specific details
232 for a given platform must still be determined through the use of ``#ifdef``.
234 Consistent Semantics
235 --------------------
237 The implementation of a ``lib/Support`` interface can vary drastically between
238 platforms. That's okay as long as the end result of the interface function is
239 the same. For example, a function to create a directory is pretty straight
240 forward on all operating system. System V IPC on the other hand isn't even
241 supported on all platforms. Instead of "supporting" System V IPC,
242 ``lib/Support`` should provide an interface to the basic concept of
243 inter-process communications. The implementations might use System V IPC if
244 that was available or named pipes, or whatever gets the job done effectively
245 for a given operating system. In all cases, the interface and the
246 implementation must be semantically consistent.