summaryrefslogtreecommitdiffstats
path: root/llvm/docs/ProgrammersManual.rst
Commit message (Collapse)AuthorAgeFilesLines
* Remove some autoconf references from docs and commentsSven van Haastregt2019-07-031-2/+2
| | | | | | | | | The autoconf build system support has been removed a while ago, remove some outdated references. Differential Revision: https://reviews.llvm.org/D63608 llvm-svn: 365013
* [Docs] Modernize references to macOSJ. Ryan Stinnett2019-05-301-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | Summary: This updates all places in documentation that refer to "Mac OS X", "OS X", etc. to instead use the modern name "macOS" when no specific version number is mentioned. If a specific version is mentioned, this attempts to use the OS name at the time of that version: * Mac OS X for 10.0 - 10.7 * OS X for 10.8 - 10.11 * macOS for 10.12 - present Reviewers: JDevlieghere Subscribers: mgorny, christof, arphaman, cfe-commits, lldb-commits, libcxx-commits, llvm-commits Tags: #clang, #lldb, #libc, #llvm Differential Revision: https://reviews.llvm.org/D62654 llvm-svn: 362113
* [llvm] Add isa_and_nonnullDon Hinton2019-04-051-0/+6
| | | | | | | | | | | | | | | | | | | Summary: Add new ``isa_and_nonnull<>`` operator that works just like the ``isa<>`` operator, except that it allows for a null pointer as an argument (which it then returns false). Reviewers: lattner, aaron.ballman, greened Reviewed By: lattner Subscribers: hubert.reinterpretcast, llvm-commits Tags: #llvm Differential Revision: https://reviews.llvm.org/D60291 llvm-svn: 357761
* Fix typo in docsDmitri Gribenko2019-02-161-1/+1
| | | | | | | | Patch by Alex Yursha. Differential Revision: https://reviews.llvm.org/D45903 llvm-svn: 354203
* [ADT] Add a fallible_iterator wrapper.Lang Hames2019-02-051-11/+69
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | A fallible iterator is one whose increment or decrement operations may fail. This would usually be supported by replacing the ++ and -- operators with methods that return error: class MyFallibleIterator { public: // ... Error inc(); Errro dec(); // ... }; The downside of this style is that it no longer conforms to the C++ iterator concept, and can not make use of standard algorithms and features such as range-based for loops. The fallible_iterator wrapper takes an iterator written in the style above and adapts it to (mostly) conform with the C++ iterator concept. It does this by providing standard ++ and -- operator implementations, returning any errors generated via a side channel (an Error reference passed into the wrapper at construction time), and immediately jumping the iterator to a known 'end' value upon error. It also marks the Error as checked any time an iterator is compared with a known end value and found to be inequal, allowing early exit from loops without redundant error checking*. Usage looks like: MyFallibleIterator I = ..., E = ...; Error Err = Error::success(); for (auto &Elem : make_fallible_range(I, E, Err)) { // Loop body is only entered when safe. // Early exits from loop body permitted without checking Err. if (SomeCondition) return; } if (Err) // Handle error. * Since failure causes a fallible iterator to jump to end, testing that a fallible iterator is not an end value implicitly verifies that the error is a success value, and so is equivalent to an error check. Reviewers: dblaikie, rupprecht Subscribers: mgorny, dexonsmith, kristina, llvm-commits Tags: #llvm Differential Revision: https://reviews.llvm.org/D57618 llvm-svn: 353237
* [doc]Update String Error documentation in Programmer ManualJames Henderson2019-02-011-4/+14
| | | | | | | | | | | | | A while back, createStringError was added to provide easier construction of StringError instances, especially with formatting options. Prior to this patch, that the documentation only mentions the standard method of using it. Since createStringError is slightly shorter to type, and also provides the formatting options, this patch updates the Programmer's Manual to use the new function in its examples, and to mention the printf formatting options. It also fixes a small typo in one of the examples and removes the unnecessary make_error_code call. llvm-svn: 352846
* [opaque pointer types] Add a FunctionCallee wrapper type, and use it.James Y Knight2019-02-011-5/+11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Recommit r352791 after tweaking DerivedTypes.h slightly, so that gcc doesn't choke on it, hopefully. Original Message: The FunctionCallee type is effectively a {FunctionType*,Value*} pair, and is a useful convenience to enable code to continue passing the result of getOrInsertFunction() through to EmitCall, even once pointer types lose their pointee-type. Then: - update the CallInst/InvokeInst instruction creation functions to take a Callee, - modify getOrInsertFunction to return FunctionCallee, and - update all callers appropriately. One area of particular note is the change to the sanitizer code. Previously, they had been casting the result of `getOrInsertFunction` to a `Function*` via `checkSanitizerInterfaceFunction`, and storing that. That would report an error if someone had already inserted a function declaraction with a mismatching signature. However, in general, LLVM allows for such mismatches, as `getOrInsertFunction` will automatically insert a bitcast if needed. As part of this cleanup, cause the sanitizer code to do the same. (It will call its functions using the expected signature, however they may have been declared.) Finally, in a small number of locations, callers of `getOrInsertFunction` actually were expecting/requiring that a brand new function was being created. In such cases, I've switched them to Function::Create instead. Differential Revision: https://reviews.llvm.org/D57315 llvm-svn: 352827
* Revert "[opaque pointer types] Add a FunctionCallee wrapper type, and use it."James Y Knight2019-01-311-11/+5
| | | | | | | | | This reverts commit f47d6b38c7a61d50db4566b02719de05492dcef1 (r352791). Seems to run into compilation failures with GCC (but not clang, where I tested it). Reverting while I investigate. llvm-svn: 352800
* [opaque pointer types] Add a FunctionCallee wrapper type, and use it.James Y Knight2019-01-311-5/+11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The FunctionCallee type is effectively a {FunctionType*,Value*} pair, and is a useful convenience to enable code to continue passing the result of getOrInsertFunction() through to EmitCall, even once pointer types lose their pointee-type. Then: - update the CallInst/InvokeInst instruction creation functions to take a Callee, - modify getOrInsertFunction to return FunctionCallee, and - update all callers appropriately. One area of particular note is the change to the sanitizer code. Previously, they had been casting the result of `getOrInsertFunction` to a `Function*` via `checkSanitizerInterfaceFunction`, and storing that. That would report an error if someone had already inserted a function declaraction with a mismatching signature. However, in general, LLVM allows for such mismatches, as `getOrInsertFunction` will automatically insert a bitcast if needed. As part of this cleanup, cause the sanitizer code to do the same. (It will call its functions using the expected signature, however they may have been declared.) Finally, in a small number of locations, callers of `getOrInsertFunction` actually were expecting/requiring that a brand new function was being created. In such cases, I've switched them to Function::Create instead. Differential Revision: https://reviews.llvm.org/D57315 llvm-svn: 352791
* Replace llvm::isPodLike<...> by llvm::is_trivially_copyable<...>Serge Guelton2019-01-201-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | As noted in https://bugs.llvm.org/show_bug.cgi?id=36651, the specialization for isPodLike<std::pair<...>> did not match the expectation of std::is_trivially_copyable which makes the memcpy optimization invalid. This patch renames the llvm::isPodLike trait into llvm::is_trivially_copyable. Unfortunately std::is_trivially_copyable is not portable across compiler / STL versions. So a portable version is provided too. Note that the following specialization were invalid: std::pair<T0, T1> llvm::Optional<T> Tests have been added to assert that former specialization are respected by the standard usage of llvm::is_trivially_copyable, and that when a decent version of std::is_trivially_copyable is available, llvm::is_trivially_copyable is compared to std::is_trivially_copyable. As of this patch, llvm::Optional is no longer considered trivially copyable, even if T is. This is to be fixed in a later patch, as it has impact on a long-running bug (see r347004) Note that GCC warns about this UB, but this got silented by https://reviews.llvm.org/D50296. Differential Revision: https://reviews.llvm.org/D54472 llvm-svn: 351701
* Remove TypeBuilder.h, and fix the few locations using it.James Y Knight2019-01-131-31/+0
| | | | | | | | | | | | | | This shortcut mechanism for creating types was added 10 years ago, but has seen almost no uptake since then, neither internally nor in external projects. The very small number of characters saved by using it does not seem worth the mental overhead of an additional type-creation API, so, delete it. Differential Revision: https://reviews.llvm.org/D56573 llvm-svn: 351020
* [TI removal] Remove discussion of `TerminatorInst` from the LLVMChandler Carruth2018-10-181-9/+2
| | | | | | documentation. llvm-svn: 344727
* [doc] Update the programmer's manual about SmallSet's iteratorKristof Umann2018-10-041-8/+6
| | | | | | | | Since rL337818, you can now iterate the SmallSet. Differential Revision: https://reviews.llvm.org/D52828 llvm-svn: 343770
* ADT: Document advantages of SmallVector<T,0> over std::vectorDuncan P. N. Exon Smith2018-07-261-7/+20
| | | | | | | | | | | | In light of the recent changes to SmallVector in r335421, r337514, and r337820, document its advantages over std::vector (see r175906 and r266909). Also add a release note. https://reviews.llvm.org/D49748 llvm-svn: 338071
* [NFC] fix trivial typos in documentsHiroshi Inoue2018-06-151-1/+1
| | | | llvm-svn: 334799
* [docs] Clarify usage of "vector" in Programmer's Manual.Eli Friedman2018-05-221-1/+1
| | | | | | | The explanation is specifically referring to std::vector; this might not be clear from the context. llvm-svn: 333036
* Docs: Fix the title underline too short.Nicola Zaghen2018-05-141-1/+1
| | | | llvm-svn: 332245
* Rename DEBUG macro to LLVM_DEBUG.Nicola Zaghen2018-05-141-9/+9
| | | | | | | | | | | | | | | | The DEBUG() macro is very generic so it might clash with other projects. The renaming was done as follows: - git grep -l 'DEBUG' | xargs sed -i 's/\bDEBUG\s\?(/LLVM_DEBUG(/g' - git diff -U0 master | ../clang/tools/clang-format/clang-format-diff.py -i -p1 -style LLVM - Manual change to APInt - Manually chage DOCS as regex doesn't match it. In the transition period the DEBUG() macro is still present and aliased to the LLVM_DEBUG() one. Differential Revision: https://reviews.llvm.org/D43624 llvm-svn: 332240
* [NFC] fix trivial typos in documents and commentsHiroshi Inoue2018-04-121-1/+1
| | | | | | "is is" -> "is", "if if" -> "if", "or or" -> "or" llvm-svn: 329878
* [docs] Use dbgs() instead of errs() for DEBUG()Jonas Devlieghere2017-12-251-5/+5
| | | | | | | | | | | | The examples in llvm/Support/Debug.h use `DEBUG(dbgs() << ...)` instead of `errs()`, so the examples in the Programmer's Manual should match that. Patch by: Moritz Sichert <moritz.sichert@googlemail.com> Differential revision: https://reviews.llvm.org/D41170 llvm-svn: 321444
* [docs] Code example fixJan Korous2017-10-241-1/+1
| | | | llvm-svn: 316425
* Refine report_fatal_error guidance after post-commit reviewAlex Bradbury2017-08-181-5/+6
| | | | | | | | | Use text suggested by Justin Bogner in post-commit review of r311146 <http://lists.llvm.org/pipermail/llvm-commits/Week-of-Mon-20170814/479898.html>, which makes it clear that report_fatal_error shouldn't be used when there is a practicable alternative. Also make this clearer in CodingStandards. llvm-svn: 311147
* Give guidance on report_fatal_error in CodingStandards.rst and ↵Alex Bradbury2017-08-181-0/+8
| | | | | | | | | | | | | | | | | | | | | | | ProgrammersManual.rst The current ProgrammersManual.rst document has a lot of well-written documentation on error handling thanks to @lhames. It suggests errors can be split cleanly into "programmatic" and "recoverable" errors. However, the reality in current LLVM seems to be there are a number of cases where a non-programmatic error is not easily recoverable. Therefore, add a note to indicate the existence of report_fatal_error for these cases. I've also added a reminder to CodingStandards.rst in the section on assertions, to indicate that llvm_unreachable and assertions should not be relied upon to report errors triggered by user input. The ProgrammersManual is also silent on the use of LLVMContext::diagnose, which is used in BPF+WebAssembly+AMDGPU to report some errors during instruction selection. I don't address that in this patch, as it's not quite clear how to fit in to the current error handling story Differential Revision: https://reviews.llvm.org/D36826 llvm-svn: 311146
* [DebugCounter] Move the semicolon out of the DEBUG_COUNTER macro and require ↵Craig Topper2017-08-101-1/+1
| | | | | | | | | | it to be placed at the end of each use. This make it consistent with STATISTIC which it will often appears near. While there move one DEBUG_COUNTER instance out of an anonymous namespace. It's already declaring a static variable so the namespace is unnecessary. llvm-svn: 310637
* [Docs] Remove a stray period from a code example in the Programmer's Manual.Craig Topper2017-08-091-1/+1
| | | | llvm-svn: 310520
* [docs] Fix a typo: iteratation -> iterationStephen Hines2017-07-251-1/+1
| | | | | | | | | | | | Reviewers: dgross Reviewed By: dgross Subscribers: dgross, llvm-commits Differential Revision: https://reviews.llvm.org/D35822 llvm-svn: 308994
* [docs] Simplify some language for Error/cantFail in the programmer's manual.Lang Hames2017-04-301-10/+9
| | | | llvm-svn: 301773
* Reverts commit r301424, r301425 and r301426Sanjoy Das2017-04-261-3/+3
| | | | | | | | | | | | Commits were: "Use WeakVH instead of WeakTrackingVH in AliasSetTracker's UnkownInsts" "Add a new WeakVH value handle; NFC" "Rename WeakVH to WeakTrackingVH; NFC" The changes assumed pointers are 8 byte aligned on all architectures. llvm-svn: 301429
* Rename WeakVH to WeakTrackingVH; NFCSanjoy Das2017-04-261-3/+3
| | | | | | | | | | | | | | | | Summary: I plan to use WeakVH to mean "nulls itself out on deletion, but does not track RAUW" in a subsequent commit. Reviewers: dblaikie, davide Reviewed By: davide Subscribers: arsenm, mehdi_amini, mcrosier, mzolotukhin, jfb, llvm-commits, nhaehnle Differential Revision: https://reviews.llvm.org/D32266 llvm-svn: 301424
* Update stale doxygen links in ProgrammersManual.rstTim Northover2017-04-031-17/+17
| | | | | | Patch by Wei-Ren Chen. llvm-svn: 299395
* Fix some indenting and line-wrapping issues identified in ProgrammersManual. ↵Daniel Berlin2017-03-131-26/+28
| | | | | | Make description of debugCounters a little clearer llvm-svn: 297656
* Add documentation on debug counters to Programmers Manual.Daniel Berlin2017-03-121-0/+63
| | | | | | | | | | Reviewers: mehdi_amini Subscribers: llvm-commits Differential Revision: https://reviews.llvm.org/D30842 llvm-svn: 297575
* Revert commit r296967, no typoSylvestre Ledru2017-03-051-1/+1
| | | | llvm-svn: 296984
* Fix a typo. Thanks to huangml. Reported here: ↵Sylvestre Ledru2017-03-041-1/+1
| | | | | | https://github.com/llvm-mirror/llvm/pull/6 llvm-svn: 296967
* [docs] Fix a think-o in the Programmer's Manual.Lang Hames2017-02-281-1/+1
| | | | llvm-svn: 296421
* [Support][Error] Add a 'cantFail' utility function for known-safe calls toLang Hames2017-02-271-4/+47
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | fallible functions. Some fallible functions (those returning Error or Expected<T>) may only fail for a subset of their inputs. For example, a "safe" square root function will succeed for all finite positive inputs: Expected<double> safeSqrt(double d) { if (d < 0 && !isnan(d) && !isinf(d)) return make_error<...>("Cannot sqrt -ve values, nans or infs"); return sqrt(d); } At a safe callsite for such a function, checking the error return value is redundant: if (auto ValOrErr = safeSqrt(42.0)) { // use *ValOrErr. } else llvm_unreachable("safeSqrt should always succeed for +ve values"); The cantFail function wraps this check and extracts the contained value, simplifying control flow: double Result = cantFail(safeSqrt(42.0)); This function should be used with care: it is a programmatic error to wrap a call with cantFail if it can in fact fail. For debug builds this will result in llvm_unreachable being called. For release builds the behavior is undefined. Use of this function is likely to be rare in library code, but more common for tool and unit-test code where inputs and mock functions may be known to be safe. llvm-svn: 296384
* [Doc] Modernize programmers manualPiotr Padlewski2017-02-251-28/+21
| | | | | | | | | | | | | | Summary: Fixed bunch of for loops to range based for loop and bunch of rendundat types with auto. Reviewers: echristo, silvas, chandlerc Subscribers: mehdi_amini, llvm-commits Differential Revision: https://reviews.llvm.org/D30338 llvm-svn: 296251
* Update Bugzilla URLs in docsIsmail Donmez2017-02-171-1/+1
| | | | llvm-svn: 295432
* fix some typos in the docSylvestre Ledru2017-01-141-1/+1
| | | | llvm-svn: 292014
* Fix missing '>' in docs (hopefully fixes bot error... )David Blaikie2016-12-201-1/+1
| | | | llvm-svn: 290187
* Add some brief documentation about GDB pretty printersDavid Blaikie2016-12-201-0/+16
| | | | llvm-svn: 290186
* Simplify format member detection in FormatVariadicPavel Labath2016-12-151-9/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | Summary: This replaces the format member search, which was quite complicated, with a more direct approach to detecting whether a class should be formatted using the format-member method. Instead we use a special type llvm::format_adapter, which every adapter must inherit from. Then the search can be simply implemented with the is_base_of type trait. Aside from the simplification, I like this way more because it makes it more explicit that you are supposed to use this type only for adapter-like formattings, and the other approach (format_provider overloads) should be used as a default (a mistake I made when first trying to use this library). The only slight change in behaviour here is that now choose the format-adapter branch even if the format member invocation will fail to compile (e.g. because it is a non-const member function and we are passing a const adapter), whereas previously we would have gone on to search for format_providers for the type. However, I think that is actually a good thing, as it probably means the programmer did something wrong. Reviewers: zturner, inglorion Subscribers: llvm-commits Differential Revision: https://reviews.llvm.org/D27679 llvm-svn: 289795
* IR: Move NumElements field from {Array,Vector}Type to SequentialType.Peter Collingbourne2016-12-021-3/+3
| | | | | | | | | | Now that PointerType is no longer a SequentialType, all SequentialTypes have an associated number of elements, so we can move that information to the base class, allowing for a number of simplifications. Differential Revision: https://reviews.llvm.org/D27122 llvm-svn: 288464
* IR: Change PointerType to derive from Type rather than SequentialType.Peter Collingbourne2016-12-021-2/+2
| | | | | | | | | | | | | | | | | | | As proposed on llvm-dev: http://lists.llvm.org/pipermail/llvm-dev/2016-October/106640.html This is for a couple of reasons: - Values of type PointerType are unlike the other SequentialTypes (arrays and vectors) in that they do not hold values of the element type. By moving PointerType we can unify certain aspects of how the other SequentialTypes are handled. - PointerType will have no place in the SequentialType hierarchy once pointee types are removed, so this is a necessary step towards removing pointee types. Differential Revision: https://reviews.llvm.org/D26595 llvm-svn: 288462
* [Support] Introduce llvm::formatv() function.Zachary Turner2016-11-111-0/+130
| | | | | | | | | | | | | | | | | | This introduces a new type-safe general purpose formatting library. It provides compile-time type safety, does not require a format specifier (since the type is deduced), and provides mechanisms for extending the format capability to user defined types, and overriding the formatting behavior for existing types. This patch additionally adds documentation for the API to the LLVM programmer's manual. Mailing List Thread: http://lists.llvm.org/pipermail/llvm-dev/2016-October/105836.html Differential Revision: https://reviews.llvm.org/D25587 llvm-svn: 286682
* NFC ProgrammersManual fixPiotr Padlewski2016-11-111-1/+1
| | | | llvm-svn: 286645
* [docs] Add a pointer to ExitOnError to the discussion of handleErrors in theLang Hames2016-11-071-2/+9
| | | | | | | | | | | | programmer's manual. ExitOnError is often a better alternative to handleErrors for tool code. This patch makes it easier to find the ExitOnError discussion when reading the handleErrors section. Thanks to Peter Collingbourne for the suggestion. llvm-svn: 286167
* [docs] remove more non-ascii stuff in the hopes to fix the bot Kostya Serebryany2016-11-011-10/+10
| | | | llvm-svn: 285668
* docs: trying to fix the docs bot by removing non-ASCII characters. The docs ↵Kostya Serebryany2016-10-311-2/+2
| | | | | | build fine on my machine, bot fail on the bot (http://lab.llvm.org:8011/builders/llvm-sphinx-docs/builds/25/steps/docs-llvm-html/logs/stdio) llvm-svn: 285639
* [libFuzzer] remove large examples from the libFuzzer docs and link to the ↵Kostya Serebryany2016-10-271-0/+1
| | | | | | libFuzzer tutorial instead; also fix a build error in another file llvm-svn: 285337
OpenPOWER on IntegriCloud