From 809500fc2c13c8173a16b052304d983864e4a1e1 Mon Sep 17 00:00:00 2001 From: Dimitry Andric Date: Mon, 8 Apr 2013 18:45:10 +0000 Subject: Vendor import of clang trunk r178860: http://llvm.org/svn/llvm-project/cfe/trunk@178860 --- .arcconfig | 4 + .gitignore | 3 + CMakeLists.txt | 27 +- CODE_OWNERS.TXT | 40 + INSTALL.txt | 2 +- LICENSE.TXT | 2 +- NOTES.txt | 3 - bindings/python/clang/cindex.py | 74 +- bindings/python/tests/cindex/test_cursor.py | 9 + .../python/tests/cindex/test_translation_unit.py | 17 + bindings/xml/comment-xml-schema.rng | 55 +- docs/AddressSanitizer.html | 171 - docs/AddressSanitizer.rst | 163 + docs/AnalyzerRegions.html | 260 - docs/AutomaticReferenceCounting.html | 2226 ----- docs/AutomaticReferenceCounting.rst | 2283 +++++ docs/Block-ABI-Apple.rst | 935 +++ docs/Block-ABI-Apple.txt | 670 +- docs/BlockLanguageSpec.rst | 361 + docs/BlockLanguageSpec.txt | 171 - docs/ClangCheck.rst | 36 + docs/ClangFormat.rst | 93 + docs/ClangPlugins.html | 170 - docs/ClangPlugins.rst | 150 + docs/ClangTools.html | 110 - docs/ClangTools.rst | 152 + docs/DriverInternals.html | 523 -- docs/DriverInternals.rst | 400 + docs/ExternalClangExamples.rst | 80 + docs/FAQ.rst | 64 + docs/HowToSetupToolingForLLVM.html | 212 - docs/HowToSetupToolingForLLVM.rst | 199 + docs/InternalsManual.html | 2019 ----- docs/InternalsManual.rst | 1810 ++++ docs/IntroductionToTheClangAST.html | 139 - docs/IntroductionToTheClangAST.rst | 135 + docs/JSONCompilationDatabase.html | 89 - docs/JSONCompilationDatabase.rst | 88 + docs/LanguageExtensions.html | 2082 ----- docs/LanguageExtensions.rst | 2000 +++++ docs/LibASTMatchers.html | 130 - docs/LibASTMatchers.rst | 134 + docs/LibASTMatchersReference.html | 1730 +++- docs/LibASTMatchersTutorial.rst | 538 ++ docs/LibFormat.rst | 56 + docs/LibTooling.html | 212 - docs/LibTooling.rst | 192 + docs/Makefile.sphinx | 163 + docs/MemorySanitizer.rst | 178 + docs/Modules.rst | 713 ++ docs/ObjectiveCLiterals.html | 423 - docs/ObjectiveCLiterals.rst | 554 ++ docs/PCHInternals.html | 658 -- docs/PCHInternals.rst | 561 ++ docs/PTHInternals.html | 179 - docs/PTHInternals.rst | 163 + docs/RAVFrontendAction.html | 224 - docs/RAVFrontendAction.rst | 216 + docs/README.txt | 1 + docs/ReleaseNotes.html | 325 - docs/ReleaseNotes.rst | 147 + docs/ThreadSanitizer.html | 126 - docs/ThreadSanitizer.rst | 126 + docs/Tooling.html | 120 - docs/Tooling.rst | 97 + docs/UsersManual.html | 1309 --- docs/UsersManual.rst | 1313 +++ docs/analyzer/DebugChecks.rst | 134 + docs/analyzer/IPA.txt | 105 +- docs/analyzer/Makefile | 155 + docs/analyzer/RegionStore.txt | 171 + docs/analyzer/conf.py | 246 + docs/analyzer/debug-checks.txt | 89 - docs/analyzer/index.rst | 23 + docs/analyzer/make.bat | 190 + docs/conf.py | 242 + docs/index.rst | 73 + docs/make.bat | 190 + docs/tools/dump_ast_matchers.py | 44 +- examples/PrintFunctionNames/PrintFunctionNames.cpp | 2 +- examples/analyzer-plugin/MainCallChecker.cpp | 4 +- examples/clang-interpreter/CMakeLists.txt | 1 + examples/clang-interpreter/main.cpp | 20 +- include/clang-c/CXCompilationDatabase.h | 6 + include/clang-c/CXString.h | 2 +- include/clang-c/Index.h | 165 +- include/clang/ARCMigrate/ARCMT.h | 2 +- include/clang/ARCMigrate/ARCMTActions.h | 2 +- include/clang/ARCMigrate/FileRemapper.h | 2 +- include/clang/AST/APValue.h | 2 +- include/clang/AST/AST.h | 2 +- include/clang/AST/ASTConsumer.h | 15 +- include/clang/AST/ASTContext.h | 253 +- include/clang/AST/ASTImporter.h | 3 + include/clang/AST/ASTMutationListener.h | 9 +- include/clang/AST/ASTTypeTraits.h | 211 + include/clang/AST/ASTUnresolvedSet.h | 86 + include/clang/AST/ASTVector.h | 12 +- include/clang/AST/Attr.h | 171 +- include/clang/AST/AttrIterator.h | 142 + include/clang/AST/BuiltinTypes.def | 14 + include/clang/AST/CMakeLists.txt | 13 + include/clang/AST/CXXInheritance.h | 4 +- include/clang/AST/CanonicalType.h | 69 +- include/clang/AST/CharUnits.h | 11 + include/clang/AST/Comment.h | 87 +- include/clang/AST/CommentCommandTraits.h | 34 +- include/clang/AST/CommentCommands.td | 92 +- .../AST/CommentHTMLNamedCharacterReferences.td | 177 + include/clang/AST/CommentLexer.h | 13 +- include/clang/AST/CommentParser.h | 9 +- include/clang/AST/CommentSema.h | 31 +- include/clang/AST/CommentVisitor.h | 4 + include/clang/AST/Decl.h | 327 +- include/clang/AST/DeclAccessPair.h | 1 + include/clang/AST/DeclBase.h | 129 +- include/clang/AST/DeclCXX.h | 587 +- include/clang/AST/DeclContextInternals.h | 24 +- include/clang/AST/DeclFriend.h | 50 +- include/clang/AST/DeclLookups.h | 1 + include/clang/AST/DeclObjC.h | 339 +- include/clang/AST/DeclOpenMP.h | 83 + include/clang/AST/DeclTemplate.h | 114 +- include/clang/AST/DeclVisitor.h | 43 +- include/clang/AST/DeclarationName.h | 85 +- include/clang/AST/DependentDiagnostic.h | 22 +- include/clang/AST/EvaluatedExprVisitor.h | 23 +- include/clang/AST/Expr.h | 367 +- include/clang/AST/ExprCXX.h | 257 +- include/clang/AST/ExprObjC.h | 126 +- include/clang/AST/ExternalASTSource.h | 28 +- include/clang/AST/LambdaMangleContext.h | 4 +- include/clang/AST/Makefile | 25 +- include/clang/AST/Mangle.h | 2 +- include/clang/AST/NSAPI.h | 14 +- include/clang/AST/NestedNameSpecifier.h | 2 +- include/clang/AST/OperationKinds.h | 5 +- include/clang/AST/PrettyPrinter.h | 19 +- include/clang/AST/RecursiveASTVisitor.h | 36 +- include/clang/AST/Stmt.h | 229 +- include/clang/AST/StmtCXX.h | 38 +- include/clang/AST/StmtGraphTraits.h | 2 +- include/clang/AST/StmtObjC.h | 37 +- include/clang/AST/TemplateBase.h | 87 +- include/clang/AST/TemplateName.h | 24 +- include/clang/AST/Type.h | 200 +- include/clang/AST/TypeLoc.h | 93 +- include/clang/AST/TypeLocVisitor.h | 2 +- include/clang/AST/TypeOrdering.h | 2 +- include/clang/AST/UnresolvedSet.h | 11 +- include/clang/AST/VTTBuilder.h | 9 - include/clang/AST/VTableBuilder.h | 23 +- include/clang/ASTMatchers/ASTMatchFinder.h | 85 +- include/clang/ASTMatchers/ASTMatchers.h | 573 +- include/clang/ASTMatchers/ASTMatchersInternal.h | 241 +- include/clang/ASTMatchers/ASTMatchersMacros.h | 284 +- include/clang/ASTMatchers/ASTTypeTraits.h | 209 - include/clang/Analysis/Analyses/Dominators.h | 7 +- include/clang/Analysis/Analyses/FormatString.h | 4 +- include/clang/Analysis/Analyses/LiveVariables.h | 2 +- include/clang/Analysis/Analyses/ThreadSafety.h | 23 +- .../clang/Analysis/Analyses/UninitializedValues.h | 5 +- include/clang/Analysis/AnalysisContext.h | 25 +- include/clang/Analysis/CFG.h | 117 +- include/clang/Analysis/CallGraph.h | 40 +- .../clang/Analysis/FlowSensitive/DataflowSolver.h | 4 +- include/clang/Analysis/ProgramPoint.h | 230 +- .../clang/Analysis/Support/BlkExprDeclBitVector.h | 2 +- include/clang/Analysis/Support/BumpVector.h | 4 +- .../Analysis/Visitors/CFGRecStmtDeclVisitor.h | 6 +- include/clang/Basic/Attr.td | 243 +- include/clang/Basic/AttrKinds.h | 1 + include/clang/Basic/Builtins.def | 41 +- include/clang/Basic/Builtins.h | 6 + include/clang/Basic/BuiltinsX86.def | 6 + include/clang/Basic/CharInfo.h | 198 + include/clang/Basic/CommentOptions.h | 34 + include/clang/Basic/ConvertUTF.h | 203 - include/clang/Basic/DeclNodes.td | 2 + include/clang/Basic/Diagnostic.h | 34 +- include/clang/Basic/DiagnosticASTKinds.td | 6 +- include/clang/Basic/DiagnosticCommentKinds.td | 41 +- include/clang/Basic/DiagnosticCommonKinds.td | 14 +- include/clang/Basic/DiagnosticDriverKinds.td | 20 +- include/clang/Basic/DiagnosticFrontendKinds.td | 24 +- include/clang/Basic/DiagnosticGroups.td | 58 +- include/clang/Basic/DiagnosticIDs.h | 14 +- include/clang/Basic/DiagnosticLexKinds.td | 89 +- include/clang/Basic/DiagnosticOptions.def | 2 + include/clang/Basic/DiagnosticOptions.h | 15 +- include/clang/Basic/DiagnosticParseKinds.td | 51 +- include/clang/Basic/DiagnosticSemaKinds.td | 519 +- .../clang/Basic/DiagnosticSerializationKinds.td | 15 +- include/clang/Basic/FileManager.h | 18 +- include/clang/Basic/FileSystemStatCache.h | 21 +- include/clang/Basic/IdentifierTable.h | 9 +- include/clang/Basic/LLVM.h | 13 +- include/clang/Basic/LangOptions.def | 23 +- include/clang/Basic/LangOptions.h | 21 +- include/clang/Basic/Linkage.h | 8 + include/clang/Basic/MacroBuilder.h | 1 + include/clang/Basic/Module.h | 124 +- include/clang/Basic/ObjCRuntime.h | 16 +- include/clang/Basic/OnDiskHashTable.h | 3 +- include/clang/Basic/OpenMPKinds.def | 23 + include/clang/Basic/OpenMPKinds.h | 37 + include/clang/Basic/OperatorPrecedence.h | 52 + include/clang/Basic/PartialDiagnostic.h | 24 +- include/clang/Basic/Sanitizers.def | 57 +- include/clang/Basic/SourceLocation.h | 22 +- include/clang/Basic/SourceManager.h | 158 +- include/clang/Basic/Specifiers.h | 13 +- include/clang/Basic/TargetCXXABI.h | 261 + include/clang/Basic/TargetInfo.h | 80 +- include/clang/Basic/TargetOptions.h | 1 + include/clang/Basic/TokenKinds.def | 92 +- include/clang/Basic/TokenKinds.h | 18 +- include/clang/Basic/TypeTraits.h | 3 + include/clang/Basic/Version.h | 3 +- include/clang/Basic/VersionTuple.h | 8 +- include/clang/Basic/Visibility.h | 76 + include/clang/CodeGen/ModuleBuilder.h | 2 + include/clang/Driver/Arg.h | 7 +- include/clang/Driver/ArgList.h | 5 +- include/clang/Driver/CC1AsOptions.td | 8 + include/clang/Driver/CC1Options.td | 47 +- include/clang/Driver/Compilation.h | 43 +- include/clang/Driver/Driver.h | 14 +- include/clang/Driver/Job.h | 2 +- include/clang/Driver/OptSpecifier.h | 4 +- include/clang/Driver/Option.h | 2 +- include/clang/Driver/Options.td | 107 +- include/clang/Driver/Phases.h | 4 + include/clang/Driver/Tool.h | 1 + include/clang/Driver/ToolChain.h | 36 +- include/clang/Driver/Types.def | 3 +- include/clang/Driver/Types.h | 13 +- include/clang/Driver/Util.h | 5 + include/clang/Edit/Commit.h | 8 +- include/clang/Edit/EditedSource.h | 12 +- include/clang/Edit/Rewriters.h | 4 +- include/clang/Format/Format.h | 131 + include/clang/Frontend/ASTUnit.h | 42 +- include/clang/Frontend/ChainedIncludesSource.h | 4 +- include/clang/Frontend/CodeGenOptions.def | 21 +- include/clang/Frontend/CodeGenOptions.h | 17 + include/clang/Frontend/CompilerInstance.h | 52 +- include/clang/Frontend/CompilerInvocation.h | 14 +- include/clang/Frontend/DiagnosticRenderer.h | 49 +- include/clang/Frontend/FrontendAction.h | 102 +- include/clang/Frontend/FrontendActions.h | 17 +- include/clang/Frontend/FrontendOptions.h | 29 +- include/clang/Frontend/LangStandard.h | 6 +- include/clang/Frontend/LangStandards.def | 12 +- include/clang/Frontend/LayoutOverrideSource.h | 5 +- include/clang/Frontend/LogDiagnosticPrinter.h | 4 +- include/clang/Frontend/MultiplexConsumer.h | 1 - include/clang/Frontend/PreprocessorOutputOptions.h | 2 +- .../clang/Frontend/SerializedDiagnosticPrinter.h | 3 +- include/clang/Frontend/TextDiagnostic.h | 20 +- include/clang/Frontend/TextDiagnosticPrinter.h | 4 +- include/clang/Frontend/Utils.h | 3 +- include/clang/Lex/DirectoryLookup.h | 34 +- include/clang/Lex/ExternalPreprocessorSource.h | 4 +- include/clang/Lex/HeaderSearch.h | 30 +- include/clang/Lex/HeaderSearchOptions.h | 67 +- include/clang/Lex/Lexer.h | 50 +- include/clang/Lex/LiteralSupport.h | 8 +- include/clang/Lex/MacroInfo.h | 471 +- include/clang/Lex/ModuleLoader.h | 41 +- include/clang/Lex/ModuleMap.h | 55 +- include/clang/Lex/PPCallbacks.h | 66 +- include/clang/Lex/PPConditionalDirectiveRecord.h | 102 + include/clang/Lex/PPMutationListener.h | 43 - include/clang/Lex/PTHManager.h | 6 +- include/clang/Lex/PreprocessingRecord.h | 97 +- include/clang/Lex/Preprocessor.h | 184 +- include/clang/Lex/PreprocessorOptions.h | 52 +- include/clang/Lex/Token.h | 12 +- include/clang/Parse/Parser.h | 147 +- include/clang/Rewrite/Core/RewriteRope.h | 3 +- include/clang/Rewrite/Core/Rewriter.h | 8 +- include/clang/Rewrite/Frontend/ASTConsumers.h | 3 +- include/clang/Rewrite/Frontend/FixItRewriter.h | 2 +- include/clang/Sema/AttributeList.h | 123 +- include/clang/Sema/CMakeLists.txt | 7 +- include/clang/Sema/CXXFieldCollector.h | 1 + include/clang/Sema/CodeCompleteConsumer.h | 37 +- include/clang/Sema/CodeCompleteOptions.h | 8 +- include/clang/Sema/DeclSpec.h | 216 +- include/clang/Sema/DelayedDiagnostic.h | 39 +- include/clang/Sema/ExternalSemaSource.h | 10 +- include/clang/Sema/IdentifierResolver.h | 3 +- include/clang/Sema/Initialization.h | 93 +- include/clang/Sema/Lookup.h | 25 +- include/clang/Sema/Makefile | 9 +- include/clang/Sema/MultiplexExternalSemaSource.h | 59 +- include/clang/Sema/Overload.h | 9 +- include/clang/Sema/Ownership.h | 3 - include/clang/Sema/Scope.h | 64 +- include/clang/Sema/ScopeInfo.h | 17 +- include/clang/Sema/Sema.h | 551 +- include/clang/Sema/SemaInternal.h | 2 +- include/clang/Sema/Template.h | 13 +- include/clang/Sema/TemplateDeduction.h | 18 +- include/clang/Sema/TypoCorrection.h | 15 +- include/clang/Serialization/ASTBitCodes.h | 103 +- include/clang/Serialization/ASTReader.h | 347 +- include/clang/Serialization/ASTWriter.h | 62 +- include/clang/Serialization/ContinuousRangeMap.h | 1 + include/clang/Serialization/GlobalModuleIndex.h | 194 + include/clang/Serialization/Module.h | 53 +- include/clang/Serialization/ModuleManager.h | 148 +- include/clang/StaticAnalyzer/Core/Analyses.def | 14 +- .../clang/StaticAnalyzer/Core/AnalyzerOptions.h | 215 +- .../StaticAnalyzer/Core/BugReporter/BugReporter.h | 28 +- .../Core/BugReporter/BugReporterVisitor.h | 125 +- .../StaticAnalyzer/Core/BugReporter/BugType.h | 1 + .../Core/BugReporter/PathDiagnostic.h | 32 +- include/clang/StaticAnalyzer/Core/Checker.h | 87 +- include/clang/StaticAnalyzer/Core/CheckerManager.h | 81 +- include/clang/StaticAnalyzer/Core/CheckerOptInfo.h | 1 + .../clang/StaticAnalyzer/Core/CheckerRegistry.h | 2 +- .../StaticAnalyzer/Core/PathDiagnosticConsumers.h | 24 +- .../StaticAnalyzer/Core/PathSensitive/APSIntType.h | 9 +- .../Core/PathSensitive/AnalysisManager.h | 2 +- .../Core/PathSensitive/BasicValueFactory.h | 3 +- .../StaticAnalyzer/Core/PathSensitive/CallEvent.h | 38 +- .../Core/PathSensitive/CheckerContext.h | 12 +- .../Core/PathSensitive/ConstraintManager.h | 14 +- .../StaticAnalyzer/Core/PathSensitive/CoreEngine.h | 12 +- .../Core/PathSensitive/Environment.h | 10 - .../Core/PathSensitive/ExplodedGraph.h | 64 +- .../StaticAnalyzer/Core/PathSensitive/ExprEngine.h | 143 +- .../Core/PathSensitive/FunctionSummary.h | 96 +- .../StaticAnalyzer/Core/PathSensitive/MemRegion.h | 61 +- .../Core/PathSensitive/ProgramState.h | 105 +- .../Core/PathSensitive/ProgramStateTrait.h | 19 +- .../Core/PathSensitive/SValBuilder.h | 5 +- .../StaticAnalyzer/Core/PathSensitive/SVals.h | 242 +- .../StaticAnalyzer/Core/PathSensitive/Store.h | 40 +- .../StaticAnalyzer/Core/PathSensitive/SubEngine.h | 22 +- .../Core/PathSensitive/SymbolManager.h | 8 +- .../Core/PathSensitive/TaintManager.h | 4 + .../StaticAnalyzer/Core/PathSensitive/WorkList.h | 6 +- include/clang/Tooling/CommonOptionsParser.h | 10 +- include/clang/Tooling/CompilationDatabase.h | 13 +- include/clang/Tooling/FileMatchTrie.h | 3 +- include/clang/Tooling/JSONCompilationDatabase.h | 10 +- include/clang/Tooling/Refactoring.h | 62 +- include/clang/Tooling/Tooling.h | 17 +- lib/ARCMigrate/ARCMT.cpp | 48 +- lib/ARCMigrate/CMakeLists.txt | 5 +- lib/ARCMigrate/FileRemapper.cpp | 6 +- lib/ARCMigrate/Internals.h | 8 +- lib/ARCMigrate/ObjCMT.cpp | 69 +- lib/ARCMigrate/PlistReporter.cpp | 4 +- lib/ARCMigrate/TransAPIUses.cpp | 2 +- lib/ARCMigrate/TransARCAssign.cpp | 2 +- lib/ARCMigrate/TransAutoreleasePool.cpp | 4 +- lib/ARCMigrate/TransBlockObjCVariable.cpp | 3 +- lib/ARCMigrate/TransEmptyStatementsAndDealloc.cpp | 2 +- lib/ARCMigrate/TransGCAttrs.cpp | 28 +- lib/ARCMigrate/TransGCCalls.cpp | 2 +- lib/ARCMigrate/TransProperties.cpp | 32 +- lib/ARCMigrate/TransProtectedScope.cpp | 202 + lib/ARCMigrate/TransRetainReleaseDealloc.cpp | 125 +- lib/ARCMigrate/TransUnbridgedCasts.cpp | 108 +- lib/ARCMigrate/TransUnusedInitDelegate.cpp | 2 +- lib/ARCMigrate/TransZeroOutPropsInDealloc.cpp | 2 +- lib/ARCMigrate/TransformActions.cpp | 2 +- lib/ARCMigrate/Transforms.cpp | 27 +- lib/ARCMigrate/Transforms.h | 10 +- lib/AST/APValue.cpp | 4 +- lib/AST/ASTConsumer.cpp | 2 +- lib/AST/ASTContext.cpp | 767 +- lib/AST/ASTDiagnostic.cpp | 567 +- lib/AST/ASTDumper.cpp | 1996 +++++ lib/AST/ASTImporter.cpp | 163 +- lib/AST/AttrImpl.cpp | 4 +- lib/AST/CMakeLists.txt | 7 +- lib/AST/CXXABI.h | 6 +- lib/AST/CXXInheritance.cpp | 43 +- lib/AST/Comment.cpp | 40 +- lib/AST/CommentBriefParser.cpp | 2 +- lib/AST/CommentCommandTraits.cpp | 34 +- lib/AST/CommentDumper.cpp | 257 - lib/AST/CommentLexer.cpp | 127 +- lib/AST/CommentParser.cpp | 66 +- lib/AST/CommentSema.cpp | 269 +- lib/AST/Decl.cpp | 1305 +-- lib/AST/DeclBase.cpp | 141 +- lib/AST/DeclCXX.cpp | 828 +- lib/AST/DeclFriend.cpp | 21 +- lib/AST/DeclGroup.cpp | 2 +- lib/AST/DeclObjC.cpp | 428 +- lib/AST/DeclOpenMP.cpp | 60 + lib/AST/DeclPrinter.cpp | 193 +- lib/AST/DeclTemplate.cpp | 61 +- lib/AST/DeclarationName.cpp | 15 + lib/AST/DumpXML.cpp | 28 +- lib/AST/Expr.cpp | 168 +- lib/AST/ExprCXX.cpp | 76 +- lib/AST/ExprClassification.cpp | 37 +- lib/AST/ExprConstant.cpp | 306 +- lib/AST/ExternalASTSource.cpp | 4 +- lib/AST/InheritViz.cpp | 2 +- lib/AST/ItaniumCXXABI.cpp | 15 +- lib/AST/ItaniumMangle.cpp | 80 +- lib/AST/LambdaMangleContext.cpp | 9 +- lib/AST/Mangle.cpp | 2 +- lib/AST/MicrosoftCXXABI.cpp | 136 +- lib/AST/MicrosoftMangle.cpp | 218 +- lib/AST/NSAPI.cpp | 39 +- lib/AST/NestedNameSpecifier.cpp | 15 +- lib/AST/RawCommentList.cpp | 6 +- lib/AST/RecordLayout.cpp | 7 +- lib/AST/RecordLayoutBuilder.cpp | 135 +- lib/AST/Stmt.cpp | 156 +- lib/AST/StmtDumper.cpp | 760 -- lib/AST/StmtPrinter.cpp | 214 +- lib/AST/TemplateBase.cpp | 21 +- lib/AST/TemplateName.cpp | 14 +- lib/AST/Type.cpp | 249 +- lib/AST/TypeLoc.cpp | 30 +- lib/AST/TypePrinter.cpp | 140 +- lib/AST/VTableBuilder.cpp | 126 +- lib/ASTMatchers/ASTMatchFinder.cpp | 236 +- lib/ASTMatchers/ASTMatchersInternal.cpp | 7 +- lib/ASTMatchers/CMakeLists.txt | 6 +- lib/Analysis/AnalysisDeclContext.cpp | 68 +- lib/Analysis/BodyFarm.cpp | 18 +- lib/Analysis/BodyFarm.h | 5 +- lib/Analysis/CFG.cpp | 166 +- lib/Analysis/CFGStmtMap.cpp | 2 +- lib/Analysis/CallGraph.cpp | 112 +- lib/Analysis/CocoaConventions.cpp | 8 +- lib/Analysis/FormatString.cpp | 11 +- lib/Analysis/FormatStringParsing.h | 2 +- lib/Analysis/LiveVariables.cpp | 38 +- lib/Analysis/PrintfFormatString.cpp | 34 +- lib/Analysis/ReachableCode.cpp | 14 +- lib/Analysis/ScanfFormatString.cpp | 4 +- lib/Analysis/ThreadSafety.cpp | 290 +- lib/Analysis/UninitializedValues.cpp | 160 +- lib/Basic/Builtins.cpp | 2 +- lib/Basic/CMakeLists.txt | 30 +- lib/Basic/CharInfo.cpp | 81 + lib/Basic/ConvertUTF.c | 571 -- lib/Basic/ConvertUTFWrapper.cpp | 76 - lib/Basic/Diagnostic.cpp | 66 +- lib/Basic/DiagnosticIDs.cpp | 72 +- lib/Basic/FileManager.cpp | 50 +- lib/Basic/FileSystemStatCache.cpp | 20 +- lib/Basic/IdentifierTable.cpp | 21 +- lib/Basic/LangOptions.cpp | 10 +- lib/Basic/Module.cpp | 134 +- lib/Basic/OpenMPKinds.cpp | 43 + lib/Basic/OperatorPrecedence.cpp | 76 + lib/Basic/SourceLocation.cpp | 2 +- lib/Basic/SourceManager.cpp | 90 +- lib/Basic/TargetInfo.cpp | 24 +- lib/Basic/Targets.cpp | 810 +- lib/Basic/TokenKinds.cpp | 1 - lib/Basic/Version.cpp | 10 +- lib/Basic/VersionTuple.cpp | 4 +- lib/CMakeLists.txt | 1 + lib/CodeGen/ABIInfo.h | 21 +- lib/CodeGen/BackendUtil.cpp | 153 +- lib/CodeGen/CGAtomic.cpp | 942 +++ lib/CodeGen/CGBlocks.cpp | 306 +- lib/CodeGen/CGBlocks.h | 35 +- lib/CodeGen/CGBuilder.h | 2 +- lib/CodeGen/CGBuiltin.cpp | 141 +- lib/CodeGen/CGCUDANV.cpp | 13 +- lib/CodeGen/CGCUDARuntime.cpp | 4 +- lib/CodeGen/CGCXX.cpp | 10 +- lib/CodeGen/CGCXXABI.cpp | 27 +- lib/CodeGen/CGCXXABI.h | 57 +- lib/CodeGen/CGCall.cpp | 617 +- lib/CodeGen/CGCall.h | 36 +- lib/CodeGen/CGClass.cpp | 627 +- lib/CodeGen/CGCleanup.cpp | 12 +- lib/CodeGen/CGDebugInfo.cpp | 905 +- lib/CodeGen/CGDebugInfo.h | 72 +- lib/CodeGen/CGDecl.cpp | 339 +- lib/CodeGen/CGDeclCXX.cpp | 32 +- lib/CodeGen/CGException.cpp | 273 +- lib/CodeGen/CGExpr.cpp | 1301 ++- lib/CodeGen/CGExprAgg.cpp | 215 +- lib/CodeGen/CGExprCXX.cpp | 159 +- lib/CodeGen/CGExprComplex.cpp | 126 +- lib/CodeGen/CGExprConstant.cpp | 40 +- lib/CodeGen/CGExprScalar.cpp | 478 +- lib/CodeGen/CGObjC.cpp | 265 +- lib/CodeGen/CGObjCGNU.cpp | 275 +- lib/CodeGen/CGObjCMac.cpp | 687 +- lib/CodeGen/CGObjCRuntime.cpp | 34 +- lib/CodeGen/CGObjCRuntime.h | 29 +- lib/CodeGen/CGOpenCLRuntime.cpp | 38 +- lib/CodeGen/CGOpenCLRuntime.h | 6 + lib/CodeGen/CGRTTI.cpp | 20 +- lib/CodeGen/CGRecordLayout.h | 182 +- lib/CodeGen/CGRecordLayoutBuilder.cpp | 431 +- lib/CodeGen/CGStmt.cpp | 94 +- lib/CodeGen/CGVTables.cpp | 224 +- lib/CodeGen/CGVTables.h | 24 +- lib/CodeGen/CGValue.h | 80 +- lib/CodeGen/CMakeLists.txt | 2 + lib/CodeGen/CodeGenAction.cpp | 20 +- lib/CodeGen/CodeGenFunction.cpp | 382 +- lib/CodeGen/CodeGenFunction.h | 276 +- lib/CodeGen/CodeGenModule.cpp | 598 +- lib/CodeGen/CodeGenModule.h | 99 +- lib/CodeGen/CodeGenTBAA.cpp | 96 +- lib/CodeGen/CodeGenTBAA.h | 57 +- lib/CodeGen/CodeGenTypes.cpp | 86 +- lib/CodeGen/CodeGenTypes.h | 6 +- lib/CodeGen/ItaniumCXXABI.cpp | 221 +- lib/CodeGen/MicrosoftCXXABI.cpp | 278 +- lib/CodeGen/ModuleBuilder.cpp | 20 +- lib/CodeGen/TargetInfo.cpp | 696 +- lib/CodeGen/TargetInfo.h | 13 +- lib/Driver/Action.cpp | 1 - lib/Driver/ArgList.cpp | 10 +- lib/Driver/CC1AsOptions.cpp | 2 +- lib/Driver/Compilation.cpp | 128 +- lib/Driver/Driver.cpp | 247 +- lib/Driver/InputInfo.h | 2 +- lib/Driver/Job.cpp | 2 - lib/Driver/OptTable.cpp | 2 +- lib/Driver/Option.cpp | 7 +- lib/Driver/Phases.cpp | 1 - lib/Driver/SanitizerArgs.h | 130 +- lib/Driver/ToolChain.cpp | 100 +- lib/Driver/ToolChains.cpp | 931 ++- lib/Driver/ToolChains.h | 172 +- lib/Driver/Tools.cpp | 1920 +++-- lib/Driver/Tools.h | 90 +- lib/Driver/Types.cpp | 76 +- lib/Driver/WindowsToolChain.cpp | 60 +- lib/Edit/Commit.cpp | 6 +- lib/Edit/EditedSource.cpp | 80 +- lib/Edit/RewriteObjCFoundationAPI.cpp | 180 +- lib/Format/CMakeLists.txt | 26 + lib/Format/Format.cpp | 1763 ++++ lib/Format/Makefile | 13 + lib/Format/TokenAnnotator.cpp | 1187 +++ lib/Format/TokenAnnotator.h | 262 + lib/Format/UnwrappedLineParser.cpp | 858 ++ lib/Format/UnwrappedLineParser.h | 201 + lib/Frontend/ASTConsumers.cpp | 26 +- lib/Frontend/ASTMerge.cpp | 4 +- lib/Frontend/ASTUnit.cpp | 117 +- lib/Frontend/CacheTokens.cpp | 6 +- lib/Frontend/ChainedIncludesSource.cpp | 19 +- lib/Frontend/CompilerInstance.cpp | 545 +- lib/Frontend/CompilerInvocation.cpp | 275 +- lib/Frontend/CreateInvocationFromCommandLine.cpp | 14 +- lib/Frontend/DependencyFile.cpp | 8 +- lib/Frontend/DependencyGraph.cpp | 15 +- lib/Frontend/DiagnosticRenderer.cpp | 326 +- lib/Frontend/FrontendAction.cpp | 40 +- lib/Frontend/FrontendActions.cpp | 157 +- lib/Frontend/FrontendOptions.cpp | 2 +- lib/Frontend/InitHeaderSearch.cpp | 228 +- lib/Frontend/InitPreprocessor.cpp | 36 +- lib/Frontend/LayoutOverrideSource.cpp | 21 +- lib/Frontend/LogDiagnosticPrinter.cpp | 2 +- lib/Frontend/MultiplexConsumer.cpp | 1 - lib/Frontend/PrintPreprocessedOutput.cpp | 60 +- lib/Frontend/SerializedDiagnosticPrinter.cpp | 214 +- lib/Frontend/TextDiagnostic.cpp | 381 +- lib/Frontend/TextDiagnosticBuffer.cpp | 26 +- lib/Frontend/TextDiagnosticPrinter.cpp | 4 +- lib/Frontend/VerifyDiagnosticConsumer.cpp | 8 +- lib/Frontend/Warnings.cpp | 18 +- lib/FrontendTool/ExecuteCompilerInvocation.cpp | 75 +- lib/FrontendTool/Makefile | 15 + lib/Headers/CMakeLists.txt | 10 + lib/Headers/altivec.h | 7850 +++++++++--------- lib/Headers/avx2intrin.h | 384 +- lib/Headers/avxintrin.h | 715 +- lib/Headers/cpuid.h | 9 +- lib/Headers/emmintrin.h | 860 +- lib/Headers/f16cintrin.h | 10 +- lib/Headers/immintrin.h | 9 + lib/Headers/mm3dnow.h | 1 + lib/Headers/mm_malloc.h | 28 +- lib/Headers/module.map | 2 +- lib/Headers/pmmintrin.h | 48 +- lib/Headers/prfchwintrin.h | 34 + lib/Headers/rdseedintrin.h | 48 + lib/Headers/smmintrin.h | 6 +- lib/Headers/stdalign.h | 5 + lib/Headers/stddef.h | 28 +- lib/Headers/stdnoreturn.h | 30 + lib/Headers/tmmintrin.h | 120 +- lib/Headers/unwind.h | 63 +- lib/Headers/x86intrin.h | 8 + lib/Headers/xmmintrin.h | 618 +- lib/Lex/CMakeLists.txt | 1 + lib/Lex/HeaderMap.cpp | 4 +- lib/Lex/HeaderSearch.cpp | 311 +- lib/Lex/Lexer.cpp | 797 +- lib/Lex/LiteralSupport.cpp | 54 +- lib/Lex/MacroArgs.cpp | 18 +- lib/Lex/MacroArgs.h | 4 +- lib/Lex/MacroInfo.cpp | 119 +- lib/Lex/ModuleMap.cpp | 428 +- lib/Lex/PPConditionalDirectiveRecord.cpp | 120 + lib/Lex/PPDirectives.cpp | 229 +- lib/Lex/PPExpressions.cpp | 28 +- lib/Lex/PPLexerChange.cpp | 53 +- lib/Lex/PPMacroExpansion.cpp | 456 +- lib/Lex/PTHLexer.cpp | 11 +- lib/Lex/Pragma.cpp | 220 +- lib/Lex/PreprocessingRecord.cpp | 189 +- lib/Lex/Preprocessor.cpp | 185 +- lib/Lex/PreprocessorLexer.cpp | 4 +- lib/Lex/TokenConcatenation.cpp | 36 +- lib/Lex/TokenLexer.cpp | 18 +- lib/Lex/UnicodeCharSets.h | 496 ++ lib/Makefile | 18 +- lib/Parse/CMakeLists.txt | 1 + lib/Parse/ParseAST.cpp | 61 +- lib/Parse/ParseCXXInlineMethods.cpp | 55 +- lib/Parse/ParseDecl.cpp | 450 +- lib/Parse/ParseDeclCXX.cpp | 373 +- lib/Parse/ParseExpr.cpp | 139 +- lib/Parse/ParseExprCXX.cpp | 74 +- lib/Parse/ParseInit.cpp | 4 +- lib/Parse/ParseObjc.cpp | 125 +- lib/Parse/ParseOpenMP.cpp | 118 + lib/Parse/ParsePragma.cpp | 46 +- lib/Parse/ParsePragma.h | 15 +- lib/Parse/ParseStmt.cpp | 114 +- lib/Parse/ParseTemplate.cpp | 197 +- lib/Parse/ParseTentative.cpp | 53 +- lib/Parse/Parser.cpp | 105 +- lib/Parse/RAIIObjectsForParser.h | 2 +- lib/Rewrite/Core/DeltaTree.cpp | 2 +- lib/Rewrite/Core/HTMLRewrite.cpp | 9 +- lib/Rewrite/Core/Rewriter.cpp | 8 +- lib/Rewrite/Core/TokenRewriter.cpp | 2 +- lib/Rewrite/Frontend/CMakeLists.txt | 1 + lib/Rewrite/Frontend/FixItRewriter.cpp | 8 +- lib/Rewrite/Frontend/FrontendActions.cpp | 14 +- lib/Rewrite/Frontend/InclusionRewriter.cpp | 4 +- lib/Rewrite/Frontend/RewriteMacros.cpp | 8 +- lib/Rewrite/Frontend/RewriteModernObjC.cpp | 568 +- lib/Rewrite/Frontend/RewriteObjC.cpp | 172 +- lib/Sema/AnalysisBasedWarnings.cpp | 144 +- lib/Sema/AttributeList.cpp | 13 +- lib/Sema/CMakeLists.txt | 2 + lib/Sema/CodeCompleteConsumer.cpp | 61 +- lib/Sema/DeclSpec.cpp | 84 +- lib/Sema/IdentifierResolver.cpp | 14 +- lib/Sema/JumpDiagnostics.cpp | 14 +- lib/Sema/MultiplexExternalSemaSource.cpp | 28 +- lib/Sema/Sema.cpp | 272 +- lib/Sema/SemaAccess.cpp | 271 +- lib/Sema/SemaAttr.cpp | 5 +- lib/Sema/SemaCXXScopeSpec.cpp | 45 +- lib/Sema/SemaCast.cpp | 132 +- lib/Sema/SemaChecking.cpp | 922 ++- lib/Sema/SemaCodeComplete.cpp | 540 +- lib/Sema/SemaDecl.cpp | 2272 +++-- lib/Sema/SemaDeclAttr.cpp | 1240 ++- lib/Sema/SemaDeclCXX.cpp | 2484 +++--- lib/Sema/SemaDeclObjC.cpp | 359 +- lib/Sema/SemaExceptionSpec.cpp | 116 +- lib/Sema/SemaExpr.cpp | 976 ++- lib/Sema/SemaExprCXX.cpp | 395 +- lib/Sema/SemaExprMember.cpp | 110 +- lib/Sema/SemaExprObjC.cpp | 340 +- lib/Sema/SemaFixItUtils.cpp | 4 +- lib/Sema/SemaInit.cpp | 439 +- lib/Sema/SemaLambda.cpp | 294 +- lib/Sema/SemaLookup.cpp | 233 +- lib/Sema/SemaObjCProperty.cpp | 468 +- lib/Sema/SemaOpenMP.cpp | 181 + lib/Sema/SemaOverload.cpp | 448 +- lib/Sema/SemaPseudoObject.cpp | 27 +- lib/Sema/SemaStmt.cpp | 201 +- lib/Sema/SemaStmtAsm.cpp | 99 +- lib/Sema/SemaStmtAttr.cpp | 4 +- lib/Sema/SemaTemplate.cpp | 208 +- lib/Sema/SemaTemplateDeduction.cpp | 104 +- lib/Sema/SemaTemplateInstantiate.cpp | 120 +- lib/Sema/SemaTemplateInstantiateDecl.cpp | 334 +- lib/Sema/SemaTemplateVariadic.cpp | 57 +- lib/Sema/SemaType.cpp | 860 +- lib/Sema/TargetAttributesSema.cpp | 76 +- lib/Sema/TreeTransform.h | 316 +- lib/Sema/TypeLocBuilder.h | 8 +- lib/Serialization/ASTCommon.cpp | 134 +- lib/Serialization/ASTCommon.h | 17 +- lib/Serialization/ASTReader.cpp | 2238 +++-- lib/Serialization/ASTReaderDecl.cpp | 200 +- lib/Serialization/ASTReaderInternals.h | 128 +- lib/Serialization/ASTReaderStmt.cpp | 55 +- lib/Serialization/ASTWriter.cpp | 974 ++- lib/Serialization/ASTWriterDecl.cpp | 78 +- lib/Serialization/ASTWriterStmt.cpp | 13 +- lib/Serialization/CMakeLists.txt | 3 + lib/Serialization/GeneratePCH.cpp | 10 +- lib/Serialization/GlobalModuleIndex.cpp | 820 ++ lib/Serialization/Module.cpp | 6 +- lib/Serialization/ModuleManager.cpp | 316 +- .../Checkers/AnalyzerStatsChecker.cpp | 18 +- lib/StaticAnalyzer/Checkers/ArrayBoundChecker.cpp | 4 +- .../Checkers/ArrayBoundCheckerV2.cpp | 35 +- lib/StaticAnalyzer/Checkers/AttrNonNullChecker.cpp | 130 - .../Checkers/BasicObjCFoundationChecks.cpp | 176 +- .../Checkers/BoolAssignmentChecker.cpp | 22 +- .../Checkers/BuiltinFunctionChecker.cpp | 5 +- lib/StaticAnalyzer/Checkers/CMakeLists.txt | 4 +- lib/StaticAnalyzer/Checkers/CStringChecker.cpp | 166 +- .../Checkers/CStringSyntaxChecker.cpp | 4 +- .../Checkers/CallAndMessageChecker.cpp | 61 +- lib/StaticAnalyzer/Checkers/CastSizeChecker.cpp | 4 +- .../Checkers/CastToStructChecker.cpp | 2 +- lib/StaticAnalyzer/Checkers/CheckObjCDealloc.cpp | 13 +- .../Checkers/CheckObjCInstMethSignature.cpp | 9 +- .../Checkers/CheckSecuritySyntaxOnly.cpp | 11 +- lib/StaticAnalyzer/Checkers/CheckSizeofPointer.cpp | 2 +- .../Checkers/CheckerDocumentation.cpp | 45 +- lib/StaticAnalyzer/Checkers/Checkers.td | 38 +- lib/StaticAnalyzer/Checkers/ChrootChecker.cpp | 2 +- lib/StaticAnalyzer/Checkers/ClangSACheckers.h | 4 +- lib/StaticAnalyzer/Checkers/DeadStoresChecker.cpp | 12 +- lib/StaticAnalyzer/Checkers/DebugCheckers.cpp | 6 +- lib/StaticAnalyzer/Checkers/DereferenceChecker.cpp | 22 +- .../Checkers/DirectIvarAssignment.cpp | 102 +- lib/StaticAnalyzer/Checkers/DivZeroChecker.cpp | 4 +- .../Checkers/DynamicTypePropagation.cpp | 66 +- .../Checkers/ExprInspectionChecker.cpp | 5 +- .../Checkers/FixedAddressChecker.cpp | 2 +- .../Checkers/GenericTaintChecker.cpp | 9 +- .../Checkers/IdempotentOperationChecker.cpp | 38 +- .../Checkers/IvarInvalidationChecker.cpp | 431 +- .../Checkers/LLVMConventionsChecker.cpp | 5 +- .../Checkers/MacOSKeychainAPIChecker.cpp | 139 +- lib/StaticAnalyzer/Checkers/MacOSXAPIChecker.cpp | 8 +- lib/StaticAnalyzer/Checkers/MallocChecker.cpp | 1096 ++- .../Checkers/MallocOverflowSecurityChecker.cpp | 18 +- .../Checkers/MallocSizeofChecker.cpp | 7 +- .../Checkers/NSAutoreleasePoolChecker.cpp | 8 +- lib/StaticAnalyzer/Checkers/NSErrorChecker.cpp | 34 +- .../Checkers/NoReturnFunctionChecker.cpp | 12 +- .../Checkers/NonNullParamChecker.cpp | 193 + lib/StaticAnalyzer/Checkers/ObjCAtSyncChecker.cpp | 6 +- .../Checkers/ObjCContainersASTChecker.cpp | 4 +- .../Checkers/ObjCContainersChecker.cpp | 9 +- .../Checkers/ObjCMissingSuperCallChecker.cpp | 166 +- .../Checkers/ObjCSelfInitChecker.cpp | 25 +- .../Checkers/ObjCUnusedIVarsChecker.cpp | 20 +- .../Checkers/PointerArithChecker.cpp | 2 +- lib/StaticAnalyzer/Checkers/PointerSubChecker.cpp | 2 +- lib/StaticAnalyzer/Checkers/PthreadLockChecker.cpp | 4 +- lib/StaticAnalyzer/Checkers/RetainCountChecker.cpp | 243 +- .../Checkers/ReturnPointerRangeChecker.cpp | 4 +- lib/StaticAnalyzer/Checkers/ReturnUndefChecker.cpp | 98 +- .../Checkers/SimpleStreamChecker.cpp | 107 +- .../Checkers/StackAddrEscapeChecker.cpp | 33 +- lib/StaticAnalyzer/Checkers/StreamChecker.cpp | 61 +- lib/StaticAnalyzer/Checkers/TaintTesterChecker.cpp | 2 +- lib/StaticAnalyzer/Checkers/TraversalChecker.cpp | 33 +- lib/StaticAnalyzer/Checkers/UndefBranchChecker.cpp | 4 +- .../Checkers/UndefCapturedBlockVarChecker.cpp | 16 +- lib/StaticAnalyzer/Checkers/UndefResultChecker.cpp | 3 +- .../Checkers/UndefinedArraySubscriptChecker.cpp | 36 +- .../Checkers/UndefinedAssignmentChecker.cpp | 2 +- lib/StaticAnalyzer/Checkers/UnixAPIChecker.cpp | 21 +- .../Checkers/UnreachableCodeChecker.cpp | 16 +- lib/StaticAnalyzer/Checkers/VLASizeChecker.cpp | 19 +- lib/StaticAnalyzer/Checkers/VirtualCallChecker.cpp | 7 +- lib/StaticAnalyzer/Core/APSIntType.cpp | 31 +- lib/StaticAnalyzer/Core/AnalysisManager.cpp | 3 +- lib/StaticAnalyzer/Core/AnalyzerOptions.cpp | 134 +- lib/StaticAnalyzer/Core/BugReporter.cpp | 651 +- lib/StaticAnalyzer/Core/BugReporterVisitors.cpp | 858 +- lib/StaticAnalyzer/Core/CallEvent.cpp | 129 +- lib/StaticAnalyzer/Core/CheckerManager.cpp | 60 +- lib/StaticAnalyzer/Core/CheckerRegistry.cpp | 3 +- lib/StaticAnalyzer/Core/CoreEngine.cpp | 54 +- lib/StaticAnalyzer/Core/Environment.cpp | 78 +- lib/StaticAnalyzer/Core/ExplodedGraph.cpp | 130 +- lib/StaticAnalyzer/Core/ExprEngine.cpp | 665 +- lib/StaticAnalyzer/Core/ExprEngineC.cpp | 123 +- lib/StaticAnalyzer/Core/ExprEngineCXX.cpp | 230 +- .../Core/ExprEngineCallAndReturn.cpp | 572 +- lib/StaticAnalyzer/Core/ExprEngineObjC.cpp | 15 +- lib/StaticAnalyzer/Core/FunctionSummary.cpp | 14 +- lib/StaticAnalyzer/Core/HTMLDiagnostics.cpp | 13 +- lib/StaticAnalyzer/Core/MemRegion.cpp | 228 +- lib/StaticAnalyzer/Core/PathDiagnostic.cpp | 219 +- lib/StaticAnalyzer/Core/PlistDiagnostics.cpp | 63 +- lib/StaticAnalyzer/Core/ProgramState.cpp | 167 +- lib/StaticAnalyzer/Core/RangeConstraintManager.cpp | 24 +- lib/StaticAnalyzer/Core/RegionStore.cpp | 1506 ++-- lib/StaticAnalyzer/Core/SValBuilder.cpp | 70 +- lib/StaticAnalyzer/Core/SVals.cpp | 64 +- .../Core/SimpleConstraintManager.cpp | 101 +- lib/StaticAnalyzer/Core/SimpleConstraintManager.h | 9 +- lib/StaticAnalyzer/Core/SimpleSValBuilder.cpp | 161 +- lib/StaticAnalyzer/Core/Store.cpp | 66 +- lib/StaticAnalyzer/Core/SymbolManager.cpp | 53 +- lib/StaticAnalyzer/Core/TextPathDiagnostics.cpp | 5 +- lib/StaticAnalyzer/Frontend/AnalysisConsumer.cpp | 257 +- .../Frontend/CheckerRegistration.cpp | 12 +- lib/StaticAnalyzer/Frontend/FrontendActions.cpp | 2 +- lib/Tooling/CommonOptionsParser.cpp | 4 +- lib/Tooling/CompilationDatabase.cpp | 11 +- lib/Tooling/FileMatchTrie.cpp | 4 +- lib/Tooling/JSONCompilationDatabase.cpp | 94 +- lib/Tooling/Refactoring.cpp | 75 +- lib/Tooling/Tooling.cpp | 43 +- runtime/compiler-rt/Makefile | 17 +- test/ARCMT/Common.h | 6 + test/ARCMT/autoreleases.m | 10 + test/ARCMT/autoreleases.m.result | 8 + test/ARCMT/block_copy_release.m | 17 + test/ARCMT/block_copy_release.m.result | 15 + test/ARCMT/check-with-pch.m | 16 + test/ARCMT/checking.m | 8 +- test/ARCMT/migrate-with-pch.m | 7 + test/ARCMT/nonobjc-to-objc-cast-2.m | 9 + test/ARCMT/objcmt-subscripting-literals-in-arc.m | 2 + .../objcmt-subscripting-literals-in-arc.m.result | 2 + test/ARCMT/objcmt-subscripting-literals.m | 4 + test/ARCMT/objcmt-subscripting-literals.m.result | 4 + test/ARCMT/objcmt-with-pch.m | 16 + test/ARCMT/objcmt-with-pch.m.result | 16 + test/ARCMT/protected-scope.m | 37 + test/ARCMT/protected-scope.m.result | 39 + test/ASTMerge/Inputs/class1.cpp | 4 + test/ASTMerge/Inputs/class2.cpp | 4 + test/ASTMerge/class.cpp | 5 + test/Analysis/Inputs/system-header-simulator-cxx.h | 36 + .../Inputs/system-header-simulator-for-malloc.h | 34 + .../system-header-simulator-for-simple-stream.h | 12 +- .../Analysis/Inputs/system-header-simulator-objc.h | 5 + test/Analysis/Inputs/system-header-simulator.h | 13 + .../Malloc+MismatchedDeallocator+NewDelete.cpp | 71 + .../Malloc+MismatchedDeallocator_intersections.cpp | 28 + test/Analysis/Malloc+NewDelete_intersections.cpp | 14 + test/Analysis/NSContainers.m | 200 + test/Analysis/NSString.m | 25 + ...wDelete+MismatchedDeallocator_intersections.cpp | 28 + test/Analysis/NewDelete-checker-test.cpp | 145 + test/Analysis/NewDelete-custom.cpp | 57 + test/Analysis/NewDelete-intersections.mm | 64 + test/Analysis/NewDelete-path-notes.cpp | 323 + test/Analysis/NewDelete-variadic.cpp | 19 + test/Analysis/NoReturn.m | 39 +- test/Analysis/PR3991.m | 17 +- test/Analysis/additive-folding-range-constraints.c | 132 + test/Analysis/additive-folding.cpp | 20 +- test/Analysis/alloc-match-dealloc.mm | 221 + test/Analysis/analyzer-config.c | 9 +- test/Analysis/analyzer-config.cpp | 11 +- test/Analysis/analyzer-stats.c | 2 +- test/Analysis/array-struct-region.c | 65 +- test/Analysis/auto-obj-dtors-cfg-output.cpp | 1 - test/Analysis/base-init.cpp | 2 +- test/Analysis/blocks-no-inline.c | 29 +- test/Analysis/blocks.m | 31 +- test/Analysis/call-invalidation.cpp | 91 + test/Analysis/casts.c | 11 + test/Analysis/cfg.cpp | 37 + test/Analysis/conditional-operator-path-notes.c | 24 +- test/Analysis/coverage.c | 24 +- test/Analysis/ctor-inlining.mm | 385 +- test/Analysis/dead-stores.cpp | 29 +- test/Analysis/debug-CallGraph.c | 18 +- test/Analysis/default-diagnostic-visitors.c | 2 +- test/Analysis/derived-to-base.cpp | 230 +- .../diagnostics/Inputs/include/sys/queue.h | 5 + .../diagnostics/deref-track-symbolic-region.c | 625 +- .../diagnostics/deref-track-symbolic-region.cpp | 29 +- test/Analysis/diagnostics/explicit-suppression.cpp | 80 + .../diagnostics/false-positive-suppression.c | 23 + test/Analysis/diagnostics/no-prune-paths.c | 21 + .../diagnostics/shortest-path-suppression.c | 19 + test/Analysis/diagnostics/undef-value-caller.c | 298 +- test/Analysis/diagnostics/undef-value-param.c | 314 +- test/Analysis/diagnostics/undef-value-param.m | 1313 ++- test/Analysis/dtor.cpp | 102 +- test/Analysis/dtors-in-dtor-cfg-output.cpp | 1 - test/Analysis/dynamic-cast.cpp | 2 +- test/Analysis/engine/replay-without-inlining.c | 2 +- test/Analysis/fields.c | 87 + test/Analysis/free.c | 2 +- test/Analysis/global-region-invalidation.c | 44 +- test/Analysis/global_region_invalidation.mm | 45 + test/Analysis/html-diags-multifile.c | 1 - test/Analysis/html-diags.c | 2 +- test/Analysis/initializer.cpp | 35 +- test/Analysis/initializers-cfg-output.cpp | 1 - test/Analysis/inline-plist.c | 30 +- test/Analysis/inline-unique-reports.c | 2 +- test/Analysis/inline.cpp | 56 +- test/Analysis/inlining/DynDispatchBifurcate.m | 2 +- test/Analysis/inlining/InlineObjCClassMethod.m | 2 +- test/Analysis/inlining/ObjCDynTypePopagation.m | 19 +- .../ObjCImproperDynamictallyDetectableCast.m | 2 +- test/Analysis/inlining/RetainCountExamples.m | 2 +- .../assume-super-init-does-not-return-nil.m | 2 +- test/Analysis/inlining/containers.cpp | 234 + test/Analysis/inlining/dyn-dispatch-bifurcate.cpp | 2 +- .../inlining/eager-reclamation-path-notes.c | 16 +- .../inlining/eager-reclamation-path-notes.cpp | 419 + .../Analysis/inlining/false-positive-suppression.c | 85 + .../inlining/false-positive-suppression.cpp | 212 + test/Analysis/inlining/inline-defensive-checks.c | 99 + test/Analysis/inlining/inline-defensive-checks.cpp | 55 + test/Analysis/inlining/inline-defensive-checks.m | 129 + test/Analysis/inlining/path-notes.c | 1050 +-- test/Analysis/inlining/path-notes.cpp | 3711 +++++++++ test/Analysis/inlining/path-notes.m | 716 +- test/Analysis/inlining/retain-count-self-init.m | 2 +- test/Analysis/inlining/stl.cpp | 4 +- test/Analysis/inlining/test_objc_inlining_option.m | 2 +- test/Analysis/keychainAPI.m | 23 +- test/Analysis/malloc-annotations.c | 8 +- test/Analysis/malloc-interprocedural.c | 20 +- test/Analysis/malloc-plist.c | 190 +- test/Analysis/malloc.c | 228 +- test/Analysis/malloc.cpp | 46 +- test/Analysis/malloc.mm | 42 +- test/Analysis/method-arg-decay.m | 6 +- test/Analysis/method-call-path-notes.cpp | 34 +- test/Analysis/method-call.cpp | 2 +- test/Analysis/misc-ps-region-store.cpp | 116 +- test/Analysis/misc-ps-region-store.m | 4 +- test/Analysis/misc-ps.c | 12 + test/Analysis/new.cpp | 86 +- test/Analysis/null-deref-path-notes.m | 264 +- test/Analysis/objc-method-coverage.m | 6 +- ...direct-ivar-assignment-in-annotated-functions.m | 63 + test/Analysis/objc_invalidation.m | 199 +- test/Analysis/operator-calls.cpp | 2 +- test/Analysis/plist-output-alternate.m | 89 +- test/Analysis/plist-output.m | 2794 ++++++- test/Analysis/pointer-to-member.cpp | 2 +- test/Analysis/pr4209.m | 8 +- test/Analysis/ptr-arith.c | 113 + test/Analysis/refcnt_naming.m | 2 +- test/Analysis/reference.cpp | 85 +- test/Analysis/reference.mm | 17 + test/Analysis/region-store.c | 36 +- test/Analysis/region-store.cpp | 28 + test/Analysis/reinterpret-cast.cpp | 70 +- test/Analysis/retain-release-cf-audited.m | 33 + test/Analysis/retain-release-inline.m | 32 + test/Analysis/retain-release-path-notes-gc.m | 10 +- test/Analysis/retain-release-path-notes.m | 87 +- test/Analysis/retain-release.m | 8755 +++++++++++--------- test/Analysis/retain-release.mm | 23 + test/Analysis/self-init.m | 27 +- test/Analysis/shallow-mode.m | 29 + test/Analysis/simple-stream-checks.c | 17 +- test/Analysis/stack-addr-ps.cpp | 14 +- test/Analysis/stackaddrleak.c | 12 +- test/Analysis/stats.c | 1 + test/Analysis/string.c | 48 +- test/Analysis/superclass.m | 222 + test/Analysis/taint-generic.c | 11 + test/Analysis/temp-obj-dtors-cfg-output.cpp | 170 +- test/Analysis/temporaries.cpp | 54 +- test/Analysis/traversal-path-unification.c | 4 +- test/Analysis/uninit-sometimes.cpp | 4 +- test/Analysis/uninit-vals.m | 113 +- test/Analysis/unix-fns.c | 172 +- test/Analysis/viewcontroller.m | 135 - test/CMakeLists.txt | 45 +- test/CXX/basic/basic.link/p6.cpp | 43 + .../basic.lookup.qual/class.qual/p2.cpp | 92 +- .../basic/basic.lookup/basic.lookup.unqual/p14.cpp | 30 + .../basic/basic.lookup/basic.lookup.unqual/p7.cpp | 2 +- test/CXX/basic/basic.start/basic.start.main/p2.cpp | 101 + .../CXX/basic/basic.start/basic.start.main/p2a.cpp | 9 - .../CXX/basic/basic.start/basic.start.main/p2b.cpp | 9 - .../CXX/basic/basic.start/basic.start.main/p2c.cpp | 5 - .../CXX/basic/basic.start/basic.start.main/p2d.cpp | 4 - .../CXX/basic/basic.start/basic.start.main/p2e.cpp | 4 - .../CXX/basic/basic.start/basic.start.main/p2f.cpp | 7 - .../CXX/basic/basic.start/basic.start.main/p2g.cpp | 5 - .../CXX/basic/basic.start/basic.start.main/p2h.cpp | 5 - .../CXX/basic/basic.start/basic.start.main/p2i.cpp | 6 - test/CXX/basic/basic.types/p10.cpp | 2 +- test/CXX/class.access/class.access.base/p5.cpp | 23 + test/CXX/class.access/class.friend/p3-cxx0x.cpp | 7 + test/CXX/class.access/class.protected/p1.cpp | 7 +- test/CXX/class.derived/class.abstract/p16.cpp | 26 + test/CXX/class.derived/class.virtual/p3-0x.cpp | 30 + .../class/class.static/class.static.data/p3.cpp | 2 +- test/CXX/class/class.union/p1.cpp | 59 +- test/CXX/class/class.union/p2-0x.cpp | 2 +- .../namespace.def/namespace.memdef/p3.cpp | 101 + .../basic.namespace/namespace.udecl/p10.cpp | 9 + test/CXX/dcl.dcl/dcl.attr/dcl.align/p5.cpp | 74 + test/CXX/dcl.dcl/dcl.attr/dcl.align/p6.cpp | 86 + test/CXX/dcl.dcl/dcl.attr/dcl.align/p7.cpp | 16 + test/CXX/dcl.dcl/dcl.attr/dcl.align/p8.cpp | 6 + test/CXX/dcl.dcl/dcl.attr/dcl.attr.depend/p1.cpp | 32 + test/CXX/dcl.dcl/dcl.attr/dcl.attr.depend/p2.cpp | 14 + test/CXX/dcl.dcl/dcl.attr/dcl.attr.noreturn/p1.cpp | 44 + test/CXX/dcl.dcl/dcl.spec/dcl.constexpr/p1.cpp | 3 +- test/CXX/dcl.dcl/dcl.spec/dcl.constexpr/p4.cpp | 3 +- test/CXX/dcl.dcl/dcl.spec/dcl.constexpr/p5.cpp | 22 +- test/CXX/dcl.dcl/dcl.spec/dcl.constexpr/p8.cpp | 22 +- .../dcl.fct.def/dcl.fct.def.default/p1.cpp | 25 + test/CXX/dcl.decl/dcl.init/dcl.init.list/p3-0x.cpp | 33 +- test/CXX/dcl.decl/dcl.init/dcl.init.ref/p5-0x.cpp | 8 + .../dcl.decl/dcl.init/dcl.init.ref/p5-examples.cpp | 14 +- test/CXX/dcl.decl/dcl.init/p5.cpp | 48 +- .../dcl.decl/dcl.meaning/dcl.fct.default/p3.cpp | 5 +- .../dcl.meaning/dcl.fct/dcl.fct.def.default/p2.cpp | 4 +- test/CXX/dcl.decl/dcl.meaning/dcl.fct/p8.cpp | 6 +- test/CXX/except/except.spec/p14-ir.cpp | 12 +- test/CXX/except/except.spec/p14.cpp | 11 + test/CXX/except/except.spec/p9-noexcept.cpp | 7 +- test/CXX/expr/expr.const/p2-0x.cpp | 13 + test/CXX/expr/expr.post/expr.call/p7-0x.cpp | 15 +- .../CXX/expr/expr.prim/expr.prim.general/p3-0x.cpp | 37 + test/CXX/expr/expr.prim/expr.prim.lambda/p19.cpp | 2 +- test/CXX/expr/expr.prim/expr.prim.lambda/p5.cpp | 3 +- .../expr/expr.prim/expr.prim.lambda/templates.cpp | 5 +- test/CXX/lex/lex.literal/lex.ext/p5.cpp | 7 + test/CXX/lex/lex.pptoken/p3-0x.cpp | 4 + test/CXX/over/over.oper/over.literal/p8.cpp | 3 +- test/CXX/special/class.copy/implicit-move.cpp | 2 +- test/CXX/special/class.copy/p12-0x.cpp | 216 + test/CXX/special/class.copy/p18-cxx11.cpp | 62 + test/CXX/special/class.copy/p23-cxx11.cpp | 2 +- test/CXX/special/class.copy/p25-0x.cpp | 202 + test/CXX/special/class.copy/p28-cxx11.cpp | 19 + test/CXX/special/class.ctor/p1.cpp | 14 +- test/CXX/special/class.ctor/p5-0x.cpp | 47 +- test/CXX/special/class.dtor/p3-0x.cpp | 6 +- test/CXX/special/class.dtor/p5-0x.cpp | 5 +- test/CXX/special/class.inhctor/elsewhere.cpp | 20 +- test/CXX/special/class.inhctor/p1.cpp | 31 + test/CXX/special/class.inhctor/p2.cpp | 87 + test/CXX/special/class.inhctor/p3.cpp | 12 +- test/CXX/special/class.inhctor/p4.cpp | 70 + test/CXX/special/class.inhctor/p7.cpp | 12 +- test/CXX/special/class.inhctor/p8.cpp | 21 + test/CXX/temp/temp.decls/temp.variadic/p5.cpp | 9 + test/CXX/temp/temp.decls/temp.variadic/p5.mm | 9 + .../temp/temp.fct.spec/temp.arg.explicit/p3-0x.cpp | 21 + .../temp.deduct/temp.deduct.call/basic.cpp | 21 +- .../temp.deduct/temp.deduct.call/p1-0x.cpp | 3 +- .../temp.deduct/temp.deduct.type/p9-0x.cpp | 13 + test/CXX/temp/temp.res/temp.dep/p3.cpp | 47 +- test/CXX/temp/temp.spec/temp.expl.spec/p2-0x.cpp | 5 + test/CXX/temp/temp.spec/temp.explicit/p1-0x.cpp | 2 +- test/CodeCompletion/constexpr.cpp | 13 + test/CodeGen/2006-01-13-StackSave.c | 4 +- test/CodeGen/2007-06-18-SextAttrAggregate.c | 8 + test/CodeGen/2008-01-07-UnusualIntSize.c | 7 +- test/CodeGen/2008-04-08-NoExceptions.c | 6 +- test/CodeGen/2008-07-30-implicit-initialization.c | 14 +- ...7-31-promotion-of-compound-pointer-arithmetic.c | 8 +- test/CodeGen/2009-10-20-GlobalDebug.c | 4 +- test/CodeGen/2010-02-16-DbgScopes.c | 6 +- test/CodeGen/2010-03-5-LexicalScope.c | 4 +- test/CodeGen/PR4611-bitfield-layout.c | 5 +- test/CodeGen/a5.c | 5 + test/CodeGen/aarch64-arguments.c | 194 + test/CodeGen/aarch64-inline-asm.c | 56 + test/CodeGen/aarch64-type-sizes.c | 90 + test/CodeGen/aarch64-varargs.c | 238 + test/CodeGen/address-safety-attr.cpp | 83 +- test/CodeGen/address-space-field1.c | 4 +- test/CodeGen/alias.c | 14 +- test/CodeGen/always-inline.c | 5 +- test/CodeGen/arm-asm-warn.c | 23 +- test/CodeGen/arm-neon-fma.c | 19 + test/CodeGen/atomic_ops.c | 5 - test/CodeGen/atomics-inlining.c | 49 + test/CodeGen/attr-coldhot.c | 4 +- test/CodeGen/attr-minsize.cpp | 40 +- test/CodeGen/attr-naked.c | 6 +- test/CodeGen/attributes.c | 23 +- test/CodeGen/bitfield-2.c | 46 +- test/CodeGen/blocks-seq.c | 18 +- test/CodeGen/bool_test.c | 16 +- test/CodeGen/bounds-checking.c | 2 +- test/CodeGen/builtin-attributes.c | 4 +- test/CodeGen/builtins-arm.c | 7 + test/CodeGen/builtins-mips.c | 7 + test/CodeGen/builtins-multiprecision.c | 150 + test/CodeGen/builtins-ppc-altivec.c | 28 +- test/CodeGen/builtins-ppc.c | 9 + test/CodeGen/builtinshufflevector2.c | 8 +- test/CodeGen/c-strings.c | 33 +- test/CodeGen/c11atomics-ios.c | 214 + test/CodeGen/c11atomics.c | 344 + test/CodeGen/catch-undef-behavior.c | 253 +- test/CodeGen/code-coverage.c | 30 + test/CodeGen/complex-convert.c | 717 ++ test/CodeGen/compound-assign-overflow.c | 36 + test/CodeGen/compound-literal.c | 34 + test/CodeGen/debug-info-args.c | 4 +- test/CodeGen/debug-info-line.c | 6 +- test/CodeGen/debug-info-scope.c | 4 +- test/CodeGen/debug-info-static.c | 2 +- test/CodeGen/debug-info-vector.c | 7 + test/CodeGen/exceptions.c | 9 + test/CodeGen/fast-math.c | 11 + test/CodeGen/finite-math.c | 11 + test/CodeGen/frame-pointer-elim.c | 40 - test/CodeGen/function-attributes.c | 51 +- test/CodeGen/functions.c | 2 +- test/CodeGen/global-blocks-lines.c | 45 + test/CodeGen/incomplete-function-type-2.c | 19 + test/CodeGen/init.c | 2 +- test/CodeGen/inline.c | 94 +- test/CodeGen/intel_ocl_bicc.c | 11 + test/CodeGen/le32-regparm.c | 2 +- test/CodeGen/libcall-declarations.c | 208 +- test/CodeGen/libcalls-complex.c | 46 + test/CodeGen/libcalls.c | 77 +- test/CodeGen/lifetime2.c | 17 + test/CodeGen/linkage-redecl.c | 10 +- test/CodeGen/mips-constraint-regs.c | 12 +- test/CodeGen/mips-constraints-mem.c | 26 + test/CodeGen/mips-target-data.c | 14 + test/CodeGen/mips-vector-arg.c | 11 +- test/CodeGen/mips16-attr.c | 17 + test/CodeGen/mips64-padding-arg.c | 32 +- test/CodeGen/mrtd.c | 4 +- test/CodeGen/ms-declspecs.c | 14 +- test/CodeGen/ms-inline-asm-64.c | 8 +- test/CodeGen/ms-inline-asm.c | 260 +- test/CodeGen/ms-inline-asm.cpp | 26 + test/CodeGen/mult-alt-generic.c | 1 - test/CodeGen/no-opt-volatile-memcpy.c | 40 + test/CodeGen/nvptx-cpus.c | 11 + test/CodeGen/packed-nest-unpacked.c | 2 +- test/CodeGen/packed-structure.c | 1 - test/CodeGen/parameter-passing.c | 12 +- test/CodeGen/ppc-atomics.c | 35 - test/CodeGen/ppc64-complex-parms.c | 184 + test/CodeGen/ppc64-complex-return.c | 129 + test/CodeGen/ppc64-extend.c | 9 +- test/CodeGen/ppc64-varargs-complex.c | 73 + test/CodeGen/pr2394.c | 3 +- test/CodeGen/pragma-weak.c | 9 +- test/CodeGen/prefetchw-builtins.c | 12 + test/CodeGen/r5.c | 5 + test/CodeGen/rdrand-builtins.c | 25 +- test/CodeGen/regparm.c | 2 +- test/CodeGen/rtm-builtins.c | 5 + test/CodeGen/sanitize-init-order.cpp | 24 + test/CodeGen/sanitize-recover.c | 17 + test/CodeGen/sanitize-thread-attr.cpp | 61 + test/CodeGen/sanitize-use-after-scope.c | 22 + test/CodeGen/split-debug-filename.c | 7 + test/CodeGen/stack-protector.c | 16 +- test/CodeGen/string-literal.c | 75 +- test/CodeGen/struct-passing.c | 7 +- test/CodeGen/tbaa-struct.cpp | 29 + test/CodeGen/tbaa.cpp | 217 + test/CodeGen/ubsan-blacklist.c | 31 + test/CodeGen/ucn-identifiers.c | 14 + test/CodeGen/unreachable.c | 4 +- test/CodeGen/unsigned-overflow.c | 125 + test/CodeGen/unsigned-promotion.c | 143 + test/CodeGen/unsigned-trapv.c | 38 + test/CodeGen/unwind-attr.c | 17 +- test/CodeGen/visibility.c | 7 + test/CodeGen/vla.c | 6 +- test/CodeGen/volatile.c | 123 +- test/CodeGen/x86_32-arguments-darwin.c | 9 +- test/CodeGen/x86_32-arguments-linux.c | 4 +- test/CodeGen/x86_32-inline-asm.c | 24 + test/CodeGen/x86_64-arguments.c | 38 + test/CodeGenCUDA/ptx-kernels.cu | 10 +- test/CodeGenCXX/2009-05-04-PureConstNounwind.cpp | 18 +- test/CodeGenCXX/2009-12-23-MissingSext.cpp | 10 +- test/CodeGenCXX/2010-07-23-DeclLoc.cpp | 4 +- test/CodeGenCXX/aarch64-arguments.cpp | 5 + test/CodeGenCXX/aarch64-cxxabi.cpp | 96 + test/CodeGenCXX/arm.cpp | 70 +- test/CodeGenCXX/assign-operator.cpp | 26 +- test/CodeGenCXX/attr.cpp | 12 +- test/CodeGenCXX/bitfield.cpp | 428 + test/CodeGenCXX/blocks-cxx11.cpp | 30 + test/CodeGenCXX/blocks.cpp | 33 +- test/CodeGenCXX/bool-bitfield.cpp | 14 + test/CodeGenCXX/builtins.cpp | 2 +- test/CodeGenCXX/c-linkage.cpp | 20 + test/CodeGenCXX/catch-undef-behavior.cpp | 210 +- test/CodeGenCXX/constructor-alias.cpp | 12 + .../constructor-destructor-return-this.cpp | 60 + test/CodeGenCXX/copy-assign-synthesis-1.cpp | 6 - test/CodeGenCXX/coverage.cpp | 7 + test/CodeGenCXX/cp-blocks-linetables.cpp | 61 + test/CodeGenCXX/cxx0x-delegating-ctors.cpp | 38 +- test/CodeGenCXX/cxx0x-initializer-array.cpp | 103 +- test/CodeGenCXX/cxx11-exception-spec.cpp | 71 +- test/CodeGenCXX/cxx11-noreturn.cpp | 10 + .../cxx11-trivial-initializer-struct.cpp | 21 + test/CodeGenCXX/debug-info-artificial-arg.cpp | 11 +- test/CodeGenCXX/debug-info-byval.cpp | 2 +- test/CodeGenCXX/debug-info-char16.cpp | 2 +- test/CodeGenCXX/debug-info-class.cpp | 44 +- test/CodeGenCXX/debug-info-dup-fwd-decl.cpp | 6 +- test/CodeGenCXX/debug-info-enum-class.cpp | 8 +- test/CodeGenCXX/debug-info-flex-member.cpp | 2 +- test/CodeGenCXX/debug-info-fwd-ref.cpp | 9 +- test/CodeGenCXX/debug-info-method.cpp | 25 +- test/CodeGenCXX/debug-info-namespace.cpp | 21 +- test/CodeGenCXX/debug-info-nullptr.cpp | 2 +- test/CodeGenCXX/debug-info-pubtypes.cpp | 4 +- test/CodeGenCXX/debug-info-rvalue-ref.cpp | 2 +- test/CodeGenCXX/debug-info-same-line.cpp | 98 + test/CodeGenCXX/debug-info-static-fns.cpp | 2 +- test/CodeGenCXX/debug-info-static-member.cpp | 41 + test/CodeGenCXX/debug-info-template-member.cpp | 6 +- test/CodeGenCXX/debug-info-template-quals.cpp | 20 +- test/CodeGenCXX/debug-info-union-template.cpp | 15 + test/CodeGenCXX/debug-info-union.cpp | 8 +- test/CodeGenCXX/debug-info-use-after-free.cpp | 3 +- test/CodeGenCXX/debug-info-zero-length-arrays.cpp | 12 + test/CodeGenCXX/debug-lambda-expressions.cpp | 50 +- test/CodeGenCXX/debug-lambda-this.cpp | 2 +- test/CodeGenCXX/default-destructor-synthesis.cpp | 4 +- test/CodeGenCXX/delete.cpp | 4 +- test/CodeGenCXX/derived-to-base.cpp | 6 +- test/CodeGenCXX/destructors.cpp | 10 +- test/CodeGenCXX/dynamic-cast-always-null.cpp | 4 +- test/CodeGenCXX/dynamic-cast-hint.cpp | 53 + test/CodeGenCXX/dynamic-cast.cpp | 7 +- test/CodeGenCXX/eh.cpp | 23 +- test/CodeGenCXX/exception-spec-decay.cpp | 33 + test/CodeGenCXX/exceptions.cpp | 82 +- test/CodeGenCXX/extern-c.cpp | 32 +- test/CodeGenCXX/global-array-destruction.cpp | 17 + test/CodeGenCXX/global-dtor-no-atexit.cpp | 10 +- test/CodeGenCXX/global-init.cpp | 4 +- test/CodeGenCXX/implicit-copy-assign-operator.cpp | 2 +- test/CodeGenCXX/implicit-copy-constructor.cpp | 5 +- test/CodeGenCXX/inheriting-constructor.cpp | 11 +- test/CodeGenCXX/key-function-vtable.cpp | 3 +- test/CodeGenCXX/lambda-expressions.cpp | 33 +- .../mangle-ms-back-references-pr13207.cpp | 4 +- test/CodeGenCXX/mangle-ms-templates.cpp | 13 + test/CodeGenCXX/mangle-ms-vector-types.cpp | 33 + test/CodeGenCXX/mangle-ms.cpp | 11 +- test/CodeGenCXX/mangle.cpp | 25 +- test/CodeGenCXX/member-functions.cpp | 63 +- test/CodeGenCXX/member-initializers.cpp | 5 +- test/CodeGenCXX/microsoft-abi-array-cookies.cpp | 4 +- test/CodeGenCXX/microsoft-abi-constructors.cpp | 24 - test/CodeGenCXX/microsoft-abi-default-cc.cpp | 4 +- test/CodeGenCXX/microsoft-abi-member-pointers.cpp | 51 + .../microsoft-abi-static-initializers.cpp | 10 +- test/CodeGenCXX/microsoft-abi-structors.cpp | 215 + .../microsoft-abi-vtables-single-inheritance.cpp | 113 + test/CodeGenCXX/no-exceptions.cpp | 4 +- test/CodeGenCXX/no-opt-volatile-memcpy.cpp | 50 + test/CodeGenCXX/noinline-template.cpp | 4 +- test/CodeGenCXX/nrvo.cpp | 7 +- test/CodeGenCXX/pod-member-memcpys.cpp | 256 + test/CodeGenCXX/pointers-to-data-members.cpp | 6 +- test/CodeGenCXX/pragma-weak.cpp | 31 + test/CodeGenCXX/predefined-expr.cpp | 2 +- test/CodeGenCXX/reference-cast.cpp | 4 +- test/CodeGenCXX/references.cpp | 9 +- test/CodeGenCXX/runtimecc.cpp | 53 + test/CodeGenCXX/sizeof-unwind-exception.cpp | 15 +- test/CodeGenCXX/temp-order.cpp | 2 +- test/CodeGenCXX/template-anonymous-types.cpp | 16 +- test/CodeGenCXX/template-linkage.cpp | 20 + test/CodeGenCXX/temporaries.cpp | 21 + test/CodeGenCXX/threadsafe-statics.cpp | 8 +- test/CodeGenCXX/thunks.cpp | 4 +- test/CodeGenCXX/trivial-constructor-init.cpp | 18 +- test/CodeGenCXX/type_visibility.cpp | 170 + test/CodeGenCXX/typeid.cpp | 4 +- test/CodeGenCXX/value-init.cpp | 6 + test/CodeGenCXX/virtual-base-cast.cpp | 8 +- test/CodeGenCXX/virtual-function-calls.cpp | 15 +- test/CodeGenCXX/visibility-inlines-hidden.cpp | 29 +- test/CodeGenCXX/visibility-ms-compat.cpp | 112 + test/CodeGenCXX/visibility.cpp | 217 +- test/CodeGenCXX/vtable-available-externally.cpp | 9 +- test/CodeGenCXX/vtable-key-function-arm.cpp | 307 + test/CodeGenCXX/vtable-key-function-ios.cpp | 189 + test/CodeGenCXX/vtable-linkage.cpp | 26 + test/CodeGenObjC/arc-arm.m | 4 +- test/CodeGenObjC/arc-block-copy-escape.m | 6 +- test/CodeGenObjC/arc-blocks.m | 63 +- .../arc-captured-32bit-block-var-layout-2.m | 50 + .../arc-captured-32bit-block-var-layout.m | 59 +- .../arc-captured-block-var-inlined-layout.m | 68 +- test/CodeGenObjC/arc-captured-block-var-layout.m | 66 +- test/CodeGenObjC/arc-exceptions.m | 14 +- test/CodeGenObjC/arc-foreach.m | 16 +- test/CodeGenObjC/arc-literals.m | 91 +- test/CodeGenObjC/arc-loadweakretained-release.m | 77 + test/CodeGenObjC/arc-no-arc-exceptions.m | 6 +- test/CodeGenObjC/arc-precise-lifetime.m | 120 + test/CodeGenObjC/arc-property.m | 55 +- test/CodeGenObjC/arc-related-result-type.m | 4 +- test/CodeGenObjC/arc-ternary-op.m | 138 + test/CodeGenObjC/arc-unopt.m | 4 +- test/CodeGenObjC/arc-unoptimized-byref-var.m | 16 + test/CodeGenObjC/arc-weak-property.m | 2 +- test/CodeGenObjC/arc-with-atthrow.m | 4 +- test/CodeGenObjC/arc.m | 307 +- test/CodeGenObjC/attr-exception.m | 27 + test/CodeGenObjC/bitfield-access.m | 16 +- test/CodeGenObjC/bitfield-ivar-offsets.m | 1 - test/CodeGenObjC/block-byref-variable-layout.m | 49 + test/CodeGenObjC/block-var-layout.m | 20 +- test/CodeGenObjC/blocks.m | 39 +- test/CodeGenObjC/boxing.m | 12 +- test/CodeGenObjC/catch-lexical-block.m | 3 +- test/CodeGenObjC/complex-double-abi.m | 9 +- test/CodeGenObjC/debug-info-block-captured-self.m | 70 + test/CodeGenObjC/debug-info-block-helper.m | 2 +- test/CodeGenObjC/debug-info-block-line.m | 89 + test/CodeGenObjC/debug-info-blocks.m | 20 +- test/CodeGenObjC/debug-info-fwddecl.m | 2 +- test/CodeGenObjC/debug-info-id-with-protocol.m | 41 + test/CodeGenObjC/debug-info-impl.m | 2 +- test/CodeGenObjC/debug-info-ivars-extension.m | 33 + test/CodeGenObjC/debug-info-ivars-indirect.m | 32 + test/CodeGenObjC/debug-info-ivars-private.m | 36 + test/CodeGenObjC/debug-info-ivars.m | 14 +- test/CodeGenObjC/debug-info-property3.m | 2 +- test/CodeGenObjC/debug-info-pubtypes.m | 2 +- test/CodeGenObjC/debug-info-self.m | 13 +- test/CodeGenObjC/debug-info-static-var.m | 10 +- test/CodeGenObjC/debug-info-synthesis.m | 4 +- test/CodeGenObjC/encode-test-6.m | 18 + test/CodeGenObjC/encode-test.m | 4 + test/CodeGenObjC/exceptions.m | 4 +- test/CodeGenObjC/extended-block-signature-encode.m | 15 + .../CodeGenObjC/externally-initialized-selectors.m | 8 + test/CodeGenObjC/gc.m | 4 +- test/CodeGenObjC/gnu-exceptions.m | 7 +- test/CodeGenObjC/interface-layout-64.m | 1 - test/CodeGenObjC/ivar-invariant.m | 68 + test/CodeGenObjC/metadata-symbols-32.m | 3 +- test/CodeGenObjC/metadata-symbols-64.m | 3 +- .../mrr-captured-block-var-inlined-layout.m | 36 +- test/CodeGenObjC/non-lazy-classes.m | 1 - test/CodeGenObjC/nonlazy-msgSend.m | 6 +- test/CodeGenObjC/ns_consume_null_check.m | 79 +- test/CodeGenObjC/objc-align.m | 1 - test/CodeGenObjC/objc-arc-container-subscripting.m | 5 +- test/CodeGenObjC/objc-literal-debugger-test.m | 4 +- test/CodeGenObjC/objc-literal-tests.m | 4 +- test/CodeGenObjC/optimized-setter.m | 1 + test/CodeGenObjC/property.m | 3 - test/CodeGenObjC/protocols-lazy.m | 1 - test/CodeGenObjC/reorder-synthesized-ivars.m | 58 + test/CodeGenObjCXX/address-safety-attr.mm | 17 +- test/CodeGenObjCXX/arc-attrs.mm | 48 + test/CodeGenObjCXX/arc-blocks.mm | 49 + test/CodeGenObjCXX/arc-exceptions.mm | 67 +- test/CodeGenObjCXX/arc-new-delete.mm | 5 +- test/CodeGenObjCXX/arc.mm | 9 +- test/CodeGenObjCXX/block-var-layout.mm | 21 +- test/CodeGenObjCXX/exceptions-legacy.mm | 80 + test/CodeGenObjCXX/exceptions.mm | 20 +- .../externally-initialized-selectors.mm | 8 + test/CodeGenObjCXX/lambda-expressions.mm | 8 +- test/CodeGenObjCXX/message.mm | 24 + test/CodeGenObjCXX/pr14474-gline-tables-only.mm | 25 + test/CodeGenObjCXX/property-object-reference-2.mm | 4 + test/CodeGenObjCXX/unknown-anytype.mm | 20 + test/CodeGenOpenCL/addr-space-struct-arg.cl | 23 + test/CodeGenOpenCL/event_t.cl | 12 + test/CodeGenOpenCL/half.cl | 15 + test/CodeGenOpenCL/kernel-arg-info.cl | 19 +- test/CodeGenOpenCL/kernel-attributes.cl | 12 +- test/CodeGenOpenCL/local.cl | 5 + test/CodeGenOpenCL/logical-ops.cl | 56 + test/CodeGenOpenCL/opencl_types.cl | 37 + test/CodeGenOpenCL/ptx-calls.cl | 7 +- test/CodeGenOpenCL/ptx-kernels.cl | 5 +- test/CodeGenOpenCL/shifts.cl | 57 + test/CodeGenOpenCL/spir32_target.cl | 22 + test/CodeGenOpenCL/spir64_target.cl | 21 + test/Coverage/objc-language-features.inc | 1 + .../lib/gcc/x86_64-unknown-linux/4.6.0/crtbeginT.o | 0 test/Driver/Inputs/hexagon_tree/gnu/bin/hexagon-as | 1 + .../Driver/Inputs/hexagon_tree/gnu/bin/hexagon-gcc | 1 + test/Driver/Inputs/hexagon_tree/gnu/bin/hexagon-ld | 1 + .../hexagon_tree/gnu/hexagon/include/c++/4.4.0/ios | 1 + .../hexagon_tree/gnu/hexagon/include/stdio.h | 1 + .../lib/gcc/hexagon/4.4.0/include-fixed/limits.h | 1 + .../gnu/lib/gcc/hexagon/4.4.0/include/stddef.h | 1 + test/Driver/Inputs/hexagon_tree/qc/bin/placeholder | 1 + test/Driver/Inputs/lit.local.cfg | 1 + .../lib/linux/libclang_rt.asan-i386.a.syms | 0 .../lib/linux/libclang_rt.asan-x86_64.a.syms | 0 .../lib/linux/libclang_rt.msan-x86_64.a.syms | 0 .../lib/linux/libclang_rt.tsan-x86_64.a.syms | 0 .../lib/linux/libclang_rt.ubsan-i386.a.syms | 0 .../lib/linux/libclang_rt.ubsan-x86_64.a.syms | 0 .../lib/linux/libclang_rt.ubsan_cxx-i386.a.syms | 0 .../lib/linux/libclang_rt.ubsan_cxx-x86_64.a.syms | 0 .../lib/x86_64-linux-gnu/.keep | 0 .../usr/include/c++/4.7/backward/.keep | 0 .../usr/include/x86_64-linux-gnu/c++/4.7/.keep | 0 .../usr/include/x86_64-linux-gnu/c++/4.7/32/.keep | 0 .../usr/lib/gcc/x86_64-linux-gnu/4.7/32/.keep | 0 .../usr/lib/gcc/x86_64-linux-gnu/4.7/32/crtbegin.o | 0 .../usr/lib/gcc/x86_64-linux-gnu/4.7/crtbegin.o | 0 test/Driver/aarch64-features.c | 5 + test/Driver/altivec.cpp | 15 - test/Driver/apple-kext-mkernel.c | 3 +- test/Driver/arm-cortex-cpus.c | 8 + test/Driver/asan-ld.c | 50 - test/Driver/bounds-checking.c | 16 +- test/Driver/claim-unused.c | 3 + test/Driver/clang-g-opts.c | 14 +- test/Driver/clang-translation.c | 102 + test/Driver/clang_f_opts.c | 32 +- test/Driver/constructors.c | 50 +- test/Driver/crash-report.c | 2 + test/Driver/darwin-debug-flags.c | 4 + test/Driver/darwin-iphone-defaults.m | 3 +- test/Driver/darwin-sanitizer-ld.c | 52 + test/Driver/darwin-sdkroot.c | 15 +- test/Driver/debug-comp-dir.S | 11 + test/Driver/debug-main-file.S | 12 + test/Driver/debug-options-as.c | 17 +- test/Driver/fast-math.c | 2 +- test/Driver/fcomment-block-commands.c | 8 + test/Driver/flags.c | 11 +- test/Driver/frame-pointer-elim.c | 30 + test/Driver/freebsd-mips-as.c | 18 +- test/Driver/freebsd.c | 11 + test/Driver/fsanitize-blacklist.c | 18 + test/Driver/fsanitize.c | 115 +- test/Driver/gold-lto.c | 25 +- test/Driver/hexagon-toolchain-elf.c | 564 ++ test/Driver/hexagon-toolchain.c | 564 ++ test/Driver/inhibit-downstream-commands.c | 6 + test/Driver/integrated-as.c | 7 + test/Driver/integrated-as.s | 6 + test/Driver/linker-opts.c | 3 +- test/Driver/linux-header-search.cpp | 28 + test/Driver/linux-ld.c | 57 + test/Driver/lit.local.cfg | 1 + test/Driver/mips-as.c | 18 +- test/Driver/mips-eleb.c | 31 + test/Driver/mips-features.c | 12 + test/Driver/mips-float.c | 41 + test/Driver/mips-long-double.c | 19 + test/Driver/modules.m | 6 + test/Driver/modules_integrated_as.c | 6 + test/Driver/ms-inline-asm.c | 15 + test/Driver/no-integrated-as-win.c | 3 + test/Driver/nodefaultlib.c | 4 +- test/Driver/objc++-cpp-output.mm | 6 + test/Driver/objc_default_synth.m | 6 + test/Driver/openbsd.c | 20 +- test/Driver/output-file-cleanup.c | 43 +- test/Driver/output-file-is-dir.c | 7 + test/Driver/pic.c | 6 + test/Driver/ppc-features.cpp | 88 + test/Driver/qa_override.c | 10 + test/Driver/r600-mcpu.cl | 50 + test/Driver/sanitizer-ld.c | 151 + test/Driver/split-debug.c | 25 + test/Driver/target-as.s | 8 + test/Driver/ubsan-ld.c | 10 - test/Driver/unknown-arg.c | 4 +- test/Driver/unknown-gcc-arch.c | 40 +- test/Driver/visibility.cpp | 34 + test/Driver/warning-options.cpp | 10 +- test/Driver/warning-options_pedantic.cpp | 2 +- test/Driver/x86_64-nacl-defines.cpp | 2 +- test/FixIt/auto-isa-fixit.m | 66 + test/FixIt/bridge-cast-in-arc.mm | 19 + test/FixIt/bridge-in-non-arc.m | 12 + test/FixIt/fixit-c90.c | 2 +- test/FixIt/fixit-cxx0x.cpp | 14 +- test/FixIt/fixit-cxx11-attributes.cpp | 51 + test/FixIt/fixit-errors-1.c | 1 - test/FixIt/fixit-errors.c | 6 +- test/FixIt/fixit-newline-style.c | 11 + test/FixIt/fixit-nsstring-compare.m | 22 + test/FixIt/fixit-objc.m | 2 +- test/FixIt/fixit-unicode.c | 13 +- test/FixIt/fixit.cpp | 8 + test/FixIt/format-darwin.m | 116 +- test/FixIt/format.m | 135 + test/FixIt/format.mm | 30 + test/FixIt/typo.c | 10 +- test/Format/basic.cpp | 6 + test/Format/diagnostic.cpp | 4 + test/Format/ranges.cpp | 11 + test/Frontend/ast-main.cpp | 22 + test/Frontend/dependency-gen-escaping.c | 17 + test/Frontend/hexagon-target-basic.c | 9 + test/Frontend/warning-options.cpp | 5 + test/Headers/c11.c | 19 + test/Headers/cxx11.cpp | 15 + test/Headers/stdbool.cpp | 5 + test/Index/IBOutletCollection.m | 6 +- .../Inputs/CommentXML/invalid-para-kind-01.xml | 9 + .../Inputs/CommentXML/invalid-para-kind-02.xml | 9 + .../Index/Inputs/CommentXML/valid-para-kind-01.xml | 27 + .../Index/annotate-comments-availability-attrs.cpp | 25 +- test/Index/annotate-comments-property-accessor.m | 62 + test/Index/annotate-comments-typedef.m | 49 + test/Index/annotate-comments.cpp | 647 +- test/Index/annotate-context-sensitive.cpp | 2 +- test/Index/annotate-deep-statements.cpp | 3 + test/Index/annotate-module.m | 12 +- test/Index/annotate-nested-name-specifier.cpp | 10 +- test/Index/annotate-tokens-cxx0x.cpp | 27 + test/Index/annotate-tokens-pp.c | 37 +- test/Index/annotate-tokens.c | 94 +- test/Index/annotate-tokens.m | 2 +- test/Index/c-index-api-loadTU-test.m | 38 +- test/Index/c-index-getCursor-pp.c | 22 +- test/Index/c-index-getCursor-test.m | 2 +- test/Index/code-completion-skip-bodies.cpp | 12 +- test/Index/codecompletion-chained.cpp | 33 + test/Index/comment-c-decls.c | 104 + test/Index/comment-cplus-decls.cpp | 171 + test/Index/comment-cplus-template-decls.cpp | 69 + test/Index/comment-custom-block-command.cpp | 38 + test/Index/comment-objc-decls.m | 175 + test/Index/comment-to-html-xml-conversion.cpp | 797 ++ test/Index/comment-xml-schema.c | 5 + test/Index/complete-declarators.m | 17 + test/Index/complete-documentation-properties.m | 92 + test/Index/complete-driver-errors.c | 24 - test/Index/complete-exprs.c | 2 +- test/Index/complete-lambdas.mm | 2 +- test/Index/complete-macro-args.c | 36 + test/Index/complete-modules.m | 9 +- test/Index/complete-objc-message.m | 19 +- test/Index/complete-stmt.c | 11 +- test/Index/complete-super.m | 3 +- test/Index/crash-recovery-code-complete.c | 4 +- test/Index/crash-recovery-modules.m | 8 +- test/Index/crash-recovery-reparse.c | 1 - test/Index/file-includes.c | 24 + test/Index/fix-its.c | 2 +- test/Index/fix-its.m | 28 + test/Index/format-comment-cdecls.c | 99 + test/Index/getcursor-preamble.h | 8 + test/Index/getcursor-preamble.m | 23 + test/Index/headerfile-comment-to-html.m | 111 + test/Index/index-file.cpp | 4 + test/Index/index-module.m | 5 +- test/Index/index-pch-with-module.m | 4 +- test/Index/index-pch.cpp | 6 +- test/Index/index-suppress-refs.m | 2 +- test/Index/linkage.c | 8 + test/Index/modules-objc-categories.m | 10 + test/Index/overriding-ftemplate-comments.cpp | 47 +- test/Index/overriding-method-comments.mm | 73 +- test/Index/preamble_macro_template.cpp | 4 +- test/Index/print-bitwidth.c | 25 + test/Index/print-type.c | 44 + test/Index/print-type.cpp | 61 + test/Index/print-type.m | 10 + test/Index/print-typekind.c | 28 - test/Index/print-typekind.m | 10 - test/Index/recursive-cxx-member-calls.cpp | 52 +- .../Index/skip-parsed-bodies/compile_commands.json | 71 + test/Index/skip-parsed-bodies/imported.h | 5 + test/Index/skip-parsed-bodies/lit.local.cfg | 1 + test/Index/skip-parsed-bodies/pragma_once.h | 10 + test/Index/skip-parsed-bodies/t.h | 30 + test/Index/skip-parsed-bodies/t1.cpp | 1 + test/Index/skip-parsed-bodies/t2.cpp | 3 + test/Index/skip-parsed-bodies/t3.cpp | 3 + test/Index/usrs.cpp | 6 +- test/Index/vector-types.c | 6 - test/Lexer/badstring_in_if0.c | 3 +- test/Lexer/builtin_redef.c | 19 + test/Lexer/c90.c | 9 +- test/Lexer/char-literal.cpp | 18 +- test/Lexer/counter.c | 13 +- test/Lexer/cxx0x_raw_string_directives.cpp | 9 + test/Lexer/has_feature_memory_sanitizer.cpp | 11 + test/Lexer/has_feature_thread_sanitizer.cpp | 11 + test/Lexer/pragma-message.c | 2 + test/Lexer/pragma-operators.cpp | 20 +- test/Lexer/pragma-region.c | 33 + test/Lexer/string_concat.cpp | 15 + test/Lexer/token-concat-2.c | 4 - test/Lexer/token-concat.c | 11 +- test/Lexer/unicode-strings.c | 21 + test/Lexer/unicode.c | 26 + test/Lexer/unknown-char.c | 4 +- test/Lexer/utf8-char-literal.cpp | 1 + test/Lexer/utf8-invalid.c | 15 + test/Misc/ast-dump-attr.cpp | 97 + test/Misc/ast-dump-color.cpp | 87 + test/Misc/ast-dump-comment.cpp | 69 + test/Misc/ast-dump-decl.c | 152 + test/Misc/ast-dump-decl.cpp | 457 + test/Misc/ast-dump-decl.m | 136 + test/Misc/ast-dump-decl.mm | 23 + test/Misc/ast-dump-stmt.c | 24 +- test/Misc/ast-dump-stmt.cpp | 14 + test/Misc/ast-dump-stmt.m | 14 +- test/Misc/ast-dump-templates.cpp | 6 +- test/Misc/ast-dump-wchar.cpp | 8 +- test/Misc/caret-diags-macros.c | 108 +- test/Misc/dev-fd-fs.c | 32 + test/Misc/diag-line-wrapping.cpp | 12 +- test/Misc/diag-macro-backtrace.c | 17 +- test/Misc/diag-presumed.c | 36 + test/Misc/diag-template-diffing-color.cpp | 42 +- test/Misc/diag-template-diffing-cxx98.cpp | 49 + test/Misc/diag-template-diffing.cpp | 258 +- test/Misc/diagnostic-crash.cpp | 39 + test/Misc/freebsd-arm-size_t.c | 9 + test/Misc/integer-literal-printing.cpp | 68 +- test/Misc/serialized-diags-frontend.c | 2 +- test/Misc/serialized-diags-no-category.c | 2 +- test/Misc/serialized-diags.c | 2 +- test/Misc/serialized-diags.m | 30 + test/Misc/warning-flags.c | 7 +- test/Modules/Inputs/Conflicts/conflict_a.h | 1 + test/Modules/Inputs/Conflicts/conflict_b.h | 1 + test/Modules/Inputs/Conflicts/module.map | 10 + .../DependsOnModule.framework/DependsOnModule | 0 .../Frameworks/Sub.framework/Headers/Sub.h | 1 + .../Frameworks/Sub.framework/Headers/Types.h | 4 + .../Sub.framework/PrivateHeaders/SubPriv.h | 3 + .../Headers/HasSubModules.h | 1 + .../PrivateHeaders/HasSubModulesPriv.h | 2 + test/Modules/Inputs/MethodPoolA.h | 6 + test/Modules/Inputs/MethodPoolASub.h | 6 + test/Modules/Inputs/MethodPoolASub2.h | 3 + test/Modules/Inputs/MethodPoolBSub.h | 4 + test/Modules/Inputs/Modified/B.h | 3 +- test/Modules/Inputs/Modified/module.map | 7 +- test/Modules/Inputs/Module.framework/Module | 0 .../Headers/MutuallyRecursive1.h | 2 +- .../Headers/MutuallyRecursive2.h | 2 +- .../Modules/Inputs/NoUmbrella.framework/NoUmbrella | 0 test/Modules/Inputs/StdDef/module.map | 11 + test/Modules/Inputs/StdDef/other.h | 2 + test/Modules/Inputs/StdDef/size_t.h | 4 + test/Modules/Inputs/autolink-sub.h | 1 + test/Modules/Inputs/autolink-sub2.h | 1 + test/Modules/Inputs/autolink.h | 1 + test/Modules/Inputs/builtin.h | 3 + test/Modules/Inputs/builtin_sub.h | 4 + test/Modules/Inputs/category_bottom.h | 4 +- test/Modules/Inputs/category_left.h | 2 +- test/Modules/Inputs/category_left_sub.h | 11 + test/Modules/Inputs/category_other.h | 2 +- test/Modules/Inputs/category_right.h | 2 +- test/Modules/Inputs/category_right_sub.h | 17 + test/Modules/Inputs/category_top.h | 9 + test/Modules/Inputs/config.h | 7 + test/Modules/Inputs/cxx-inline-namespace.h | 11 + test/Modules/Inputs/cxx-linkage-cache.h | 11 + test/Modules/Inputs/cxx-many-overloads.h | 2004 +++++ test/Modules/Inputs/def.h | 9 + test/Modules/Inputs/diag_pragma.h | 3 + test/Modules/Inputs/diamond.h | 2 +- test/Modules/Inputs/diamond_bottom.h | 4 +- test/Modules/Inputs/diamond_left.h | 2 +- test/Modules/Inputs/diamond_right.h | 2 +- test/Modules/Inputs/ignored_macros.h | 8 + test/Modules/Inputs/linkage-merge-bar.h | 3 + test/Modules/Inputs/linkage-merge-foo.h | 2 + test/Modules/Inputs/linkage-merge-sub.h | 11 + test/Modules/Inputs/macros_left.h | 4 +- test/Modules/Inputs/macros_right.h | 4 +- test/Modules/Inputs/macros_top.h | 4 +- test/Modules/Inputs/module.map | 92 + test/Modules/Inputs/namespaces-left.h | 9 +- test/Modules/Inputs/namespaces-right.h | 9 +- test/Modules/Inputs/oldname/module.map | 4 + test/Modules/Inputs/oldname/new_name.h | 1 + test/Modules/Inputs/redecl-merge-bottom-prefix.h | 4 + test/Modules/Inputs/redecl-merge-bottom.h | 9 +- test/Modules/Inputs/redecl-merge-left-left.h | 2 +- test/Modules/Inputs/redecl-merge-left.h | 11 +- test/Modules/Inputs/redecl-merge-right.h | 7 +- test/Modules/Inputs/redecl-merge-top.h | 2 + test/Modules/Inputs/templates-left.h | 2 +- test/Modules/Inputs/templates-right.h | 2 +- test/Modules/Inputs/weird_objc.h | 1 + .../Inputs/wildcard-submodule-exports/C_one.h | 4 +- .../Inputs/wildcard-submodule-exports/C_two.h | 4 +- test/Modules/auto-module-import.m | 2 +- test/Modules/autolink.m | 40 + test/Modules/build-fail-notes.m | 31 + test/Modules/builtins.m | 16 + test/Modules/compiler_builtins.m | 9 +- test/Modules/config_macros.m | 28 + test/Modules/conflicts.m | 7 + test/Modules/cstd.m | 10 +- test/Modules/cxx-inline-namespace.cpp | 6 + test/Modules/cxx-linkage-cache.cpp | 8 + test/Modules/cxx-many-overloads.cpp | 9 + test/Modules/cycles.c | 17 +- test/Modules/decldef.m | 28 + test/Modules/decldef.mm | 32 +- test/Modules/diag-pragma.c | 13 + test/Modules/diamond-pch.c | 12 +- test/Modules/diamond.c | 12 +- test/Modules/direct-module-import.m | 2 +- test/Modules/driver.c | 8 +- test/Modules/epic-fail.m | 13 + test/Modules/global_index.m | 19 + test/Modules/header-import.m | 4 +- test/Modules/ignored_macros.m | 49 + test/Modules/import-decl.cpp | 4 +- test/Modules/inferred-frameworks.m | 4 +- test/Modules/inferred-submodules.m | 6 +- test/Modules/irgen.c | 6 +- test/Modules/linkage-merge.cpp | 13 + test/Modules/linkage-merge.m | 27 + test/Modules/load_failure.c | 12 +- test/Modules/lookup.cpp | 12 +- test/Modules/lookup.m | 12 +- test/Modules/macros.c | 48 +- test/Modules/method_pool.m | 50 +- test/Modules/modify-module.m | 20 +- test/Modules/module-private.cpp | 10 +- test/Modules/module_file_info.m | 34 + test/Modules/namespaces.cpp | 31 +- test/Modules/normal-module-map.cpp | 14 +- test/Modules/objc-categories.m | 72 +- test/Modules/objc_redef.m | 13 + test/Modules/on-demand-build-warnings.m | 5 - test/Modules/on-demand-build.m | 10 +- test/Modules/on-demand-macros.m | 6 +- test/Modules/prune.m | 46 + test/Modules/redecl-merge.m | 33 +- test/Modules/redecl-merge2.m | 8 + test/Modules/redecl-namespaces.mm | 10 +- test/Modules/redeclarations.m | 10 +- test/Modules/renamed.m | 8 + test/Modules/requires.m | 4 +- test/Modules/stddef.m | 7 + test/Modules/subframeworks.m | 17 +- test/Modules/submodules-preprocess.cpp | 12 +- test/Modules/submodules.cpp | 12 +- test/Modules/submodules.m | 4 +- test/Modules/templates.mm | 8 +- test/Modules/wildcard-submodule-exports.cpp | 8 +- test/OpenMP/linking.c | 16 + test/OpenMP/no_option.c | 6 + test/OpenMP/no_option_no_warn.c | 6 + test/OpenMP/openmp_common.c | 9 + test/OpenMP/option_warn.c | 5 + test/OpenMP/predefined_macro.c | 34 + test/OpenMP/threadprivate_ast_print.cpp | 43 + test/OpenMP/threadprivate_messages.cpp | 119 + test/PCH/Inputs/cxx-method.h | 3 + test/PCH/chain-late-anonymous-namespace.cpp | 2 + test/PCH/crash-12631281.cpp | 40 + test/PCH/cxx-constexpr.cpp | 3 + test/PCH/cxx-method.cpp | 6 + test/PCH/cxx-templates.cpp | 8 +- test/PCH/cxx-templates.h | 49 + test/PCH/cxx0x-default-delete.cpp | 12 + test/PCH/floating-literal.c | 18 + test/PCH/irgen-rdar13114142.mm | 39 + test/PCH/macro-redef.c | 28 + test/PCH/missing-file.cpp | 1 + test/PCH/modified-header-crash.c | 5 +- test/PCH/modified-header-error.c | 2 +- test/PCH/multiple-include-pch.c | 18 + test/PCH/objc_container.m | 5 +- test/PCH/objc_stmts.m | 10 +- test/PCH/ocl_types.cl | 26 + test/PCH/ocl_types.h | 25 + test/PCH/thread-safety-attrs.cpp | 317 + test/PCH/undefined-internal.c | 15 + test/Parser/MicrosoftExtensions.c | 5 +- test/Parser/asm.c | 6 + test/Parser/atomic.c | 35 + test/Parser/attr-availability.c | 2 +- test/Parser/attributes.mm | 25 + test/Parser/c11-noreturn.c | 18 + test/Parser/c1x-alignas.c | 2 +- test/Parser/crash-report.c | 9 + test/Parser/cxx-casting.cpp | 6 +- test/Parser/cxx-class.cpp | 11 + test/Parser/cxx-decl.cpp | 65 +- test/Parser/cxx-undeclared-identifier.cpp | 2 - test/Parser/cxx0x-ambig.cpp | 24 +- test/Parser/cxx0x-attributes.cpp | 81 +- test/Parser/cxx0x-decl.cpp | 40 + test/Parser/cxx11-base-spec-attributes.cpp | 10 + test/Parser/cxx11-brace-initializers.cpp | 11 + test/Parser/cxx11-stmt-attributes.cpp | 40 +- test/Parser/missing-closing-rbrace.m | 3 + test/Parser/ms-inline-asm.c | 31 +- test/Parser/objcxx0x-lambda-expressions.mm | 2 +- test/Parser/objcxx11-attributes.mm | 12 +- test/Parser/objcxx11-protocol-in-template.mm | 15 + test/Parser/opencl-image-access.cl | 2 - test/Parser/parser_overflow.c | 14 +- test/Parser/placeholder-recovery.m | 2 +- test/Parser/prefix-attributes.m | 8 - test/Parser/recovery.cpp | 7 + test/Parser/warn-semicolon-before-method-body.m | 22 + test/Preprocessor/_Pragma-dependency.c | 5 +- test/Preprocessor/_Pragma-physloc.c | 5 +- test/Preprocessor/aarch64-target-features.c | 30 + test/Preprocessor/builtin_line.c | 6 +- test/Preprocessor/c90.c | 5 + test/Preprocessor/disabled-cond-diags.c | 3 +- test/Preprocessor/feature_tests.c | 20 + test/Preprocessor/first-line-indent.c | 7 + test/Preprocessor/has_include.c | 66 +- test/Preprocessor/hash_line.c | 9 +- test/Preprocessor/init.c | 195 +- test/Preprocessor/invalid-__has_warning1.c | 5 + test/Preprocessor/invalid-__has_warning2.c | 5 + test/Preprocessor/iwithprefix.c | 17 + test/Preprocessor/line-directive-output.c | 4 + test/Preprocessor/macro-multiline.c | 8 - test/Preprocessor/macro-multiline.c.ignoreme | 8 + test/Preprocessor/macro_arg_slocentry_merge.c | 7 + test/Preprocessor/macro_arg_slocentry_merge.h | 7 + test/Preprocessor/macro_expand.c | 8 +- test/Preprocessor/macro_expandloc.c | 9 +- test/Preprocessor/macro_expandloc2.c | 6 - test/Preprocessor/macro_fn.c | 12 +- test/Preprocessor/macro_misc.c | 14 + test/Preprocessor/macro_rescan.c | 14 +- test/Preprocessor/macro_space.c | 3 +- test/Preprocessor/macro_variadic.cl | 3 + test/Preprocessor/microsoft-import.c | 11 +- test/Preprocessor/output_paste_avoid.c | 33 - test/Preprocessor/output_paste_avoid.cpp | 47 + test/Preprocessor/pp-record.c | 11 + test/Preprocessor/pragma_diagnostic.c | 2 +- test/Preprocessor/pragma_microsoft.c | 7 +- test/Preprocessor/pragma_unknown.c | 3 +- test/Preprocessor/predefined-arch-macros.c | 161 +- test/Preprocessor/predefined-macros.c | 18 + test/Preprocessor/print_line_count.c | 5 +- test/Preprocessor/print_line_include.c | 6 + test/Preprocessor/print_line_include.h | 1 + test/Preprocessor/skipping_unclean.c | 3 +- test/Preprocessor/stringize_space.c | 12 +- test/Preprocessor/stringize_space2.c | 6 - test/Preprocessor/traditional-cpp.c | 82 +- test/Preprocessor/ucn-allowed-chars.c | 78 + test/Preprocessor/ucn-pp-identifier.c | 106 + test/Preprocessor/utf8-allowed-chars.c | 68 + test/Preprocessor/warn-disabled-macro-expansion.c | 10 +- test/Preprocessor/warning_tests.c | 27 +- test/Rewriter/line-generation-test.m | 40 + test/Rewriter/modern-write-bf-abi.mm | 120 + test/Rewriter/objc-modern-property-bitfield.m | 43 + test/Rewriter/rewrite-line-directive.m | 18 + test/Rewriter/rewrite-modern-qualified-type.mm | 11 + test/Rewriter/rewrite-modern-throw.m | 26 + test/Rewriter/unnamed-bf-modern-write.mm | 16 +- test/Sema/128bitint.c | 14 +- test/Sema/address_spaces.c | 19 +- test/Sema/alignas.c | 17 +- test/Sema/alloc_size.c | 3 +- test/Sema/anonymous-struct-union.c | 2 +- test/Sema/asm.c | 7 + test/Sema/ast-print.c | 14 +- test/Sema/atomic-ops.c | 8 + test/Sema/attr-availability.c | 13 +- test/Sema/attr-cleanup.c | 4 + test/Sema/attr-mode.c | 2 + test/Sema/attr-print.c | 21 + test/Sema/attr-regparm.c | 2 +- test/Sema/attr-used.c | 2 +- test/Sema/attr-visibility.c | 4 +- test/Sema/attr-weak.c | 6 + test/Sema/block-return.c | 11 + test/Sema/builtins.c | 15 + test/Sema/callingconv.c | 4 +- test/Sema/compare.c | 16 +- test/Sema/complex-imag.c | 4 +- test/Sema/decl-invalid.c | 4 +- test/Sema/declspec.c | 2 +- test/Sema/expr-address-of.c | 12 +- test/Sema/expr-comma-c99.c | 2 +- test/Sema/expr-comma.c | 2 +- test/Sema/exprs.c | 2 +- test/Sema/extern-redecl.c | 13 + test/Sema/format-strings-fixit.c | 8 +- test/Sema/format-strings.c | 3 + test/Sema/function-redecl.c | 2 - test/Sema/gnu89.c | 2 +- test/Sema/i-c-e.c | 2 + test/Sema/implicit-cast-dump.c | 15 + test/Sema/inline.c | 10 + test/Sema/invalid-cast.cpp | 11 + test/Sema/invalid-decl.c | 8 + test/Sema/memset-invalid-1.c | 15 + test/Sema/merge-decls.c | 54 + test/Sema/mips16_attr_allowed.c | 27 + test/Sema/mips16_attr_not_allowed.c | 7 + test/Sema/ms-inline-asm-invalid-arch.c | 5 + test/Sema/ms-inline-asm.c | 11 +- test/Sema/nowarn-documentation-property.m | 15 + test/Sema/parentheses.cpp | 12 + test/Sema/pid_t.c | 11 + test/Sema/ppc-bool.c | 4 + test/Sema/private-extern.c | 1 + test/Sema/return-noreturn.c | 5 + test/Sema/return.c | 5 + test/Sema/static-assert.c | 35 +- test/Sema/struct-decl.c | 2 +- test/Sema/switch-1.c | 22 + test/Sema/types.c | 2 +- test/Sema/ucn-cstring.c | 2 +- test/Sema/ucn-identifiers.c | 35 + test/Sema/uninit-det-order.c | 13 + test/Sema/unused-expr-system-header.c | 6 +- test/Sema/unused-expr.c | 29 +- test/Sema/varargs.c | 2 +- test/Sema/varargs_unreachable.c | 14 + test/Sema/variadic-promotion.c | 13 + test/Sema/warn-documentation-crlf.c | 13 + test/Sema/warn-documentation.cpp | 114 + test/Sema/warn-documentation.m | 74 + test/Sema/warn-duplicate-enum.c | 92 + test/Sema/warn-main-return-type.c | 49 + test/Sema/warn-main.c | 33 + test/Sema/warn-missing-prototypes.c | 8 +- test/Sema/warn-sizeof-array-decay.c | 18 + test/Sema/warn-type-safety-mpi-hdf5.c | 10 +- test/Sema/warn-unreachable.c | 8 +- test/Sema/warn-unused-variables-werror.c | 6 + test/Sema/warn-vla.c | 12 + test/Sema/wchar.c | 2 +- test/SemaCXX/MicrosoftExtensions.cpp | 4 + test/SemaCXX/address-of-temporary.cpp | 7 + test/SemaCXX/address-of.cpp | 14 +- test/SemaCXX/address-space-initialize.cpp | 25 + test/SemaCXX/alias-template.cpp | 4 +- test/SemaCXX/alignof-sizeof-reference.cpp | 6 +- test/SemaCXX/altivec.cpp | 2 +- test/SemaCXX/anonymous-struct.cpp | 4 +- test/SemaCXX/anonymous-union.cpp | 12 +- test/SemaCXX/array-bound-merge.cpp | 3 + test/SemaCXX/array-bounds.cpp | 4 +- test/SemaCXX/ast-print.cpp | 56 + test/SemaCXX/atomic-type.cxx | 25 +- test/SemaCXX/attr-cxx0x.cpp | 45 +- test/SemaCXX/attr-deprecated.cpp | 13 +- test/SemaCXX/attr-no-sanitize-address.cpp | 37 + test/SemaCXX/attr-no-sanitize-memory.cpp | 37 + test/SemaCXX/attr-no-sanitize-thread.cpp | 37 + test/SemaCXX/attr-nonnull.cpp | 21 + test/SemaCXX/attr-print.cpp | 18 + test/SemaCXX/attr-regparm.cpp | 4 +- test/SemaCXX/attr-weak.cpp | 7 + test/SemaCXX/attr-weakref.cpp | 5 +- test/SemaCXX/auto-pragma.cpp | 12 + test/SemaCXX/blocks.cpp | 35 +- test/SemaCXX/borland-extensions.cpp | 12 +- test/SemaCXX/builtins.cpp | 4 + test/SemaCXX/c99-variable-length-array-cxx11.cpp | 26 + test/SemaCXX/c99-variable-length-array.cpp | 5 +- test/SemaCXX/class-base-member-init.cpp | 8 + test/SemaCXX/compare.cpp | 150 +- test/SemaCXX/condition.cpp | 11 +- test/SemaCXX/conditional-expr.cpp | 4 +- test/SemaCXX/constant-expression-cxx11.cpp | 4 +- test/SemaCXX/constructor-initializer.cpp | 12 +- test/SemaCXX/conversion.cpp | 10 +- test/SemaCXX/copy-constructor-error.cpp | 40 +- test/SemaCXX/crash-lambda-12645424.cpp | 43 + test/SemaCXX/cxx0x-class.cpp | 6 +- test/SemaCXX/cxx0x-cursory-default-delete.cpp | 18 +- test/SemaCXX/cxx0x-defaulted-functions.cpp | 41 +- test/SemaCXX/cxx0x-initializer-aggregates.cpp | 16 +- test/SemaCXX/cxx0x-initializer-constructor.cpp | 59 +- test/SemaCXX/cxx0x-initializer-references.cpp | 7 + .../cxx0x-initializer-stdinitializerlist.cpp | 17 + test/SemaCXX/cxx11-ast-print.cpp | 6 +- test/SemaCXX/cxx11-attr-print.cpp | 77 + test/SemaCXX/cxx11-gnu-attrs.cpp | 55 + test/SemaCXX/cxx11-user-defined-literals.cpp | 6 + test/SemaCXX/cxx98-compat.cpp | 29 +- test/SemaCXX/decl-microsoft-call-conv.cpp | 86 + test/SemaCXX/default-arg-special-member.cpp | 12 - test/SemaCXX/empty-class-layout.cpp | 15 + test/SemaCXX/enum-scoped.cpp | 14 + test/SemaCXX/exceptions.cpp | 25 + test/SemaCXX/extern-c.cpp | 58 + test/SemaCXX/friend.cpp | 16 + test/SemaCXX/function-extern-c.cpp | 58 + test/SemaCXX/implicit-member-functions.cpp | 69 +- test/SemaCXX/lambda-expressions.cpp | 4 + test/SemaCXX/linkage-spec.cpp | 4 + test/SemaCXX/linkage2.cpp | 154 + test/SemaCXX/member-expr.cpp | 5 + test/SemaCXX/member-init.cpp | 16 + test/SemaCXX/member-pointer-ms.cpp | 175 +- ...issing-namespace-qualifier-typo-corrections.cpp | 2 +- test/SemaCXX/new-delete.cpp | 11 + test/SemaCXX/nullptr.cpp | 2 +- test/SemaCXX/overload-decl.cpp | 3 + test/SemaCXX/overload-member-call.cpp | 8 + test/SemaCXX/overloaded-builtin-operators.cpp | 3 +- test/SemaCXX/overloaded-operator.cpp | 25 + test/SemaCXX/pragma-weak.cpp | 8 + test/SemaCXX/pseudo-destructors.cpp | 7 +- test/SemaCXX/qualified-names-print.cpp | 15 - test/SemaCXX/return.cpp | 24 +- test/SemaCXX/scope-check.cpp | 12 + test/SemaCXX/sourceranges.cpp | 5 +- test/SemaCXX/storage-class.cpp | 2 +- test/SemaCXX/switch-implicit-fallthrough.cpp | 94 +- test/SemaCXX/type-traits.cpp | 122 +- test/SemaCXX/typo-correction.cpp | 24 + test/SemaCXX/undefined-inline.cpp | 57 + test/SemaCXX/undefined-internal.cpp | 142 + test/SemaCXX/uninitialized.cpp | 55 +- test/SemaCXX/virtual-override-x64.cpp | 36 + test/SemaCXX/virtual-override-x86.cpp | 33 + test/SemaCXX/visibility.cpp | 12 + test/SemaCXX/warn-bad-memaccess.cpp | 5 + test/SemaCXX/warn-enum-compare.cpp | 4 +- test/SemaCXX/warn-func-not-needed.cpp | 44 + test/SemaCXX/warn-reinterpret-base-class.cpp | 323 + test/SemaCXX/warn-reorder-ctor-initialization.cpp | 11 + test/SemaCXX/warn-static-const-float.cpp | 21 + test/SemaCXX/warn-thread-safety-analysis.cpp | 205 +- test/SemaCXX/warn-unsequenced.cpp | 103 + test/SemaCXX/warn-unused-filescoped.cpp | 41 +- test/SemaCXX/warn-unused-result.cpp | 38 +- test/SemaCXX/warn-variable-not-needed.cpp | 27 + test/SemaCXX/warn-vla.cpp | 27 + test/SemaObjC/arc-decls.m | 8 +- test/SemaObjC/arc-objc-lifetime.m | 62 +- test/SemaObjC/arc-property-lifetime.m | 43 +- test/SemaObjC/arc-property.m | 20 +- test/SemaObjC/arc.m | 39 + test/SemaObjC/attr-availability.m | 13 + test/SemaObjC/attr-deprecated.m | 19 + test/SemaObjC/bad-receiver-1.m | 3 +- test/SemaObjC/blocks.m | 24 +- test/SemaObjC/boxing-illegal-types.m | 58 - test/SemaObjC/boxing-illegal.m | 75 + test/SemaObjC/builtin_objc_lib_functions.m | 2 +- test/SemaObjC/builtin_objc_msgSend.m | 16 + test/SemaObjC/category-1.m | 3 +- test/SemaObjC/compare-qualified-id.m | 3 +- test/SemaObjC/conditional-expr.m | 4 +- test/SemaObjC/crash-on-objc-bool-literal.m | 9 +- test/SemaObjC/debugger-cast-result-to-id.m | 2 + test/SemaObjC/default-synthesize-3.m | 72 + test/SemaObjC/enum-fixed-type.m | 12 +- test/SemaObjC/error-missing-getter.m | 31 +- test/SemaObjC/error-outof-scope-property-use.m | 29 + test/SemaObjC/format-strings-objc.m | 6 +- .../forward-protocol-incomplete-impl-warn.m | 20 + test/SemaObjC/gcc-cast-ext.m | 7 +- test/SemaObjC/generic-selection.m | 17 + test/SemaObjC/iboutlet.m | 31 +- test/SemaObjC/illegal-nonarc-bridged-cast.m | 11 +- test/SemaObjC/incomplete-implementation.m | 9 +- test/SemaObjC/instancetype.m | 38 +- test/SemaObjC/message.m | 10 +- test/SemaObjC/method-undef-category-warn-1.m | 16 +- test/SemaObjC/method-undef-extension-warn-1.m | 6 +- test/SemaObjC/method-undefined-warn-1.m | 20 +- test/SemaObjC/no-protocol-option-tests.m | 4 +- test/SemaObjC/no-warning-unavail-unimp.m | 4 +- test/SemaObjC/objc-literal-comparison.m | 3 + test/SemaObjC/property-3.m | 21 +- test/SemaObjC/property-4.m | 2 +- test/SemaObjC/property-category-3.m | 2 +- test/SemaObjC/property-category-impl.m | 29 + test/SemaObjC/property-in-class-extension.m | 7 +- .../property-noninherited-availability-attr.m | 32 + test/SemaObjC/property-user-setter.m | 4 +- test/SemaObjC/protocol-archane.m | 6 +- test/SemaObjC/related-result-type-inference.m | 2 +- test/SemaObjC/selector-3.m | 29 + test/SemaObjC/super-property-notation.m | 25 +- test/SemaObjC/super.m | 3 +- test/SemaObjC/typo-correction.m | 21 + test/SemaObjC/undef-protocol-methods-1.m | 5 +- test/SemaObjC/warn-cast-of-sel-expr.m | 3 + test/SemaObjC/warn-deprecated-implementations.m | 13 +- test/SemaObjC/warn-direct-ivar-access.m | 28 +- test/SemaObjC/warn-isa-ref.m | 24 +- test/SemaObjC/warn-retain-block-property.m | 43 +- test/SemaObjC/warning-missing-selector-name.m | 4 +- test/SemaObjC/weak-property.m | 4 +- test/SemaObjCXX/arc-0x.mm | 8 + test/SemaObjCXX/arc-nsconsumed-errors.mm | 32 + test/SemaObjCXX/arc-templates.mm | 9 + test/SemaObjCXX/arc-unbridged-cast.mm | 9 + .../capturing-flexible-array-in-block.mm | 8 + test/SemaObjCXX/debugger-cast-result-to-id.mm | 34 +- test/SemaObjCXX/instancetype.mm | 216 + test/SemaObjCXX/instantiate-expr.mm | 4 +- test/SemaObjCXX/parameters.mm | 3 + test/SemaObjCXX/properties.mm | 37 +- test/SemaObjCXX/unknown-anytype.mm | 45 + test/SemaOpenCL/endian-attr.cl | 9 + test/SemaOpenCL/event_t.cl | 17 + test/SemaOpenCL/event_t_overload.cl | 11 + test/SemaOpenCL/half.cl | 40 + test/SemaOpenCL/invalid-kernel-attrs.cl | 16 + test/SemaOpenCL/invalid-kernel.cl | 7 + test/SemaOpenCL/invalid-logical-ops-1.1.cl | 57 + test/SemaOpenCL/invalid-logical-ops-1.2.cl | 57 + test/SemaOpenCL/sampler_t.cl | 13 + test/SemaOpenCL/sampler_t_overload.cl | 12 + test/SemaOpenCL/shifts.cl | 17 + test/SemaOpenCL/storageclass.cl | 2 +- test/SemaOpenCL/unsupported.cl | 9 + test/SemaTemplate/alignas.cpp | 23 + test/SemaTemplate/class-template-id.cpp | 2 +- test/SemaTemplate/default-expr-arguments-2.cpp | 4 +- test/SemaTemplate/default-expr-arguments.cpp | 19 + test/SemaTemplate/dependent-names.cpp | 23 + test/SemaTemplate/derived.cpp | 18 + test/SemaTemplate/destructor-template.cpp | 19 + test/SemaTemplate/example-dynarray.cpp | 1 + test/SemaTemplate/friend-template.cpp | 20 + test/SemaTemplate/fun-template-def.cpp | 8 + test/SemaTemplate/instantiate-init.cpp | 4 +- .../instantiate-member-initializers.cpp | 16 + test/SemaTemplate/instantiate-type.cpp | 13 +- test/SemaTemplate/operator-template.cpp | 2 +- .../recursive-template-instantiation.cpp | 2 +- test/SemaTemplate/temp_arg.cpp | 2 +- test/SemaTemplate/temp_arg_nontype.cpp | 16 +- test/SemaTemplate/temp_arg_nontype_cxx11.cpp | 10 + test/SemaTemplate/temp_arg_type.cpp | 4 +- test/TableGen/DiagnosticBase.inc | 35 + test/TableGen/anonymous-groups.td | 42 + test/TableGen/lit.local.cfg | 1 + test/TableGen/tg-fixits.td | 41 + .../auto-detect-from-source-parent-of-cwd.cpp | 2 + test/Tooling/auto-detect-from-source-parent.cpp | 2 + test/Tooling/auto-detect-from-source.cpp | 2 + test/Tooling/clang-check-ast-dump.cpp | 29 +- test/Tooling/clang-check-autodetect-dir.cpp | 2 + test/Tooling/clang-check-pwd.cpp | 2 + test/Tooling/pch.cpp | 12 +- test/Unit/lit.cfg | 5 + test/lit.cfg | 24 +- test/lit.site.cfg.in | 1 + tools/CMakeLists.txt | 1 + tools/Makefile | 2 +- tools/arcmt-test/CMakeLists.txt | 1 + tools/arcmt-test/Makefile | 2 +- tools/arcmt-test/arcmt-test.cpp | 4 +- tools/c-arcmt-test/Makefile | 4 +- tools/c-index-test/CMakeLists.txt | 3 +- tools/c-index-test/Makefile | 9 +- tools/c-index-test/c-index-test.c | 456 +- tools/clang-check/CMakeLists.txt | 1 + tools/clang-check/ClangCheck.cpp | 6 +- tools/clang-check/Makefile | 2 +- tools/clang-format/CMakeLists.txt | 17 + tools/clang-format/ClangFormat.cpp | 152 + tools/clang-format/Makefile | 24 + tools/clang-format/clang-format-diff.py | 115 + tools/clang-format/clang-format.py | 60 + tools/diagtool/CMakeLists.txt | 1 + tools/diagtool/DiagTool.cpp | 2 +- tools/diagtool/DiagTool.h | 2 +- tools/diagtool/ListWarnings.cpp | 6 +- tools/diagtool/Makefile | 2 +- tools/diagtool/ShowEnabledWarnings.cpp | 3 +- tools/diagtool/TreeView.cpp | 8 +- tools/driver/CMakeLists.txt | 2 + tools/driver/Makefile | 29 +- tools/driver/cc1_main.cpp | 20 +- tools/driver/cc1as_main.cpp | 33 +- tools/driver/driver.cpp | 119 +- tools/libclang/ARCMigrate.cpp | 11 +- tools/libclang/CIndex.cpp | 1826 ++-- tools/libclang/CIndexCXX.cpp | 25 +- tools/libclang/CIndexCodeCompletion.cpp | 108 +- tools/libclang/CIndexDiagnostic.cpp | 35 +- tools/libclang/CIndexHigh.cpp | 254 +- tools/libclang/CIndexInclusionStack.cpp | 7 +- tools/libclang/CIndexUSRs.cpp | 174 +- tools/libclang/CIndexer.cpp | 6 +- tools/libclang/CIndexer.h | 33 +- tools/libclang/CLog.h | 101 + tools/libclang/CMakeLists.txt | 7 +- tools/libclang/CXComment.cpp | 212 +- tools/libclang/CXComment.h | 7 +- tools/libclang/CXCompilationDatabase.cpp | 24 +- tools/libclang/CXCursor.cpp | 255 +- tools/libclang/CXCursor.h | 100 +- tools/libclang/CXLoadedDiagnostic.cpp | 129 +- tools/libclang/CXLoadedDiagnostic.h | 4 +- tools/libclang/CXSourceLocation.cpp | 99 +- tools/libclang/CXSourceLocation.h | 6 +- tools/libclang/CXStoredDiagnostic.cpp | 17 +- tools/libclang/CXString.cpp | 147 +- tools/libclang/CXString.h | 82 +- tools/libclang/CXTranslationUnit.h | 30 +- tools/libclang/CXType.cpp | 110 +- tools/libclang/CursorVisitor.h | 29 +- tools/libclang/IndexBody.cpp | 1 - tools/libclang/IndexDecl.cpp | 75 +- tools/libclang/IndexTypeSourceInfo.cpp | 1 - tools/libclang/Indexing.cpp | 340 +- tools/libclang/IndexingContext.cpp | 79 +- tools/libclang/IndexingContext.h | 9 +- tools/libclang/Makefile | 15 +- tools/libclang/RecursiveASTVisitor.h | 16 +- tools/libclang/SimpleFormatContext.h | 75 + tools/libclang/libclang.exports | 7 + tools/scan-build/ccc-analyzer | 25 +- tools/scan-build/scan-build | 162 +- tools/scan-build/set-xcode-analyzer | 10 +- unittests/AST/ASTContextParentMapTest.cpp | 71 + unittests/AST/CMakeLists.txt | 1 + unittests/AST/CommentLexer.cpp | 168 +- unittests/AST/CommentParser.cpp | 18 +- unittests/AST/DeclPrinterTest.cpp | 47 +- unittests/AST/Makefile | 6 +- unittests/AST/MatchVerifier.h | 196 + unittests/AST/SourceLocationTest.cpp | 202 +- unittests/AST/StmtPrinterTest.cpp | 11 +- unittests/ASTMatchers/ASTMatchersTest.cpp | 549 +- unittests/ASTMatchers/ASTMatchersTest.h | 2 +- unittests/ASTMatchers/CMakeLists.txt | 1 + unittests/ASTMatchers/Makefile | 6 +- unittests/Basic/CMakeLists.txt | 1 + unittests/Basic/CharInfoTest.cpp | 499 ++ unittests/Basic/FileManagerTest.cpp | 5 +- unittests/Basic/SourceManagerTest.cpp | 30 +- unittests/CMakeLists.txt | 1 + unittests/Format/CMakeLists.txt | 18 + unittests/Format/FormatTest.cpp | 3590 ++++++++ unittests/Format/Makefile | 19 + unittests/Frontend/CMakeLists.txt | 1 + unittests/Frontend/FrontendActionTest.cpp | 10 +- unittests/Frontend/Makefile | 2 +- unittests/Lex/CMakeLists.txt | 2 +- unittests/Lex/LexerTest.cpp | 28 +- unittests/Lex/PPCallbacksTest.cpp | 22 +- unittests/Lex/PPConditionalDirectiveRecordTest.cpp | 150 + unittests/Lex/PreprocessingRecordTest.cpp | 144 - unittests/Makefile | 16 +- unittests/Tooling/CMakeLists.txt | 1 + unittests/Tooling/CompilationDatabaseTest.cpp | 67 +- unittests/Tooling/Makefile | 2 +- unittests/Tooling/RecursiveASTVisitorTest.cpp | 5 +- unittests/Tooling/RefactoringCallbacksTest.cpp | 6 +- unittests/Tooling/RefactoringTest.cpp | 8 +- unittests/Tooling/RewriterTestContext.h | 8 +- unittests/Tooling/TestVisitor.h | 7 +- unittests/Tooling/ToolingTest.cpp | 36 +- utils/C++Tests/Clang-Code-Compile/lit.local.cfg | 26 - utils/C++Tests/Clang-Code-Syntax/lit.local.cfg | 25 - utils/C++Tests/Clang-Syntax/lit.local.cfg | 24 - utils/C++Tests/LLVM-Code-Compile/lit.local.cfg | 48 - utils/C++Tests/LLVM-Code-Symbols/check-symbols | 54 - utils/C++Tests/LLVM-Code-Symbols/lit.local.cfg | 48 - utils/C++Tests/LLVM-Code-Syntax/lit.local.cfg | 46 - utils/C++Tests/LLVM-Syntax/lit.local.cfg | 24 - utils/C++Tests/lit.cfg | 27 - utils/C++Tests/stdc++-Syntax/lit.local.cfg | 17 - utils/ClangDataFormat.py | 58 +- utils/OptionalTests/Extra/README.txt | 3 - .../OptionalTests/Extra/Runtime/darwin-clang_rt.c | 338 - utils/OptionalTests/README.txt | 4 - utils/OptionalTests/lit.cfg | 26 - utils/SummarizeErrors | 117 - utils/TableGen/CMakeLists.txt | 1 + utils/TableGen/ClangASTNodesEmitter.cpp | 4 + utils/TableGen/ClangAttrEmitter.cpp | 431 +- utils/TableGen/ClangCommentCommandInfoEmitter.cpp | 54 +- ...ngCommentHTMLNamedCharacterReferenceEmitter.cpp | 85 + utils/TableGen/ClangCommentHTMLTagsEmitter.cpp | 5 +- utils/TableGen/ClangDiagnosticsEmitter.cpp | 127 +- utils/TableGen/OptParserEmitter.cpp | 7 +- utils/TableGen/TableGen.cpp | 30 +- utils/TableGen/TableGenBackends.h | 4 + utils/analyzer/CmpRuns.py | 72 +- utils/analyzer/SATestBuild.py | 8 +- utils/find-unused-diagnostics.sh | 18 +- utils/valgrind/x86_64-pc-linux-gnu_gcc-4.3.3.supp | 7 + www/OpenProjects.html | 32 +- www/analyzer/annotations.html | 72 +- www/analyzer/available_checks.html | 3 +- www/analyzer/checker_dev_manual.html | 38 +- www/analyzer/content.css | 1 + www/analyzer/dev_cxx.html | 37 +- www/analyzer/faq.html | 16 +- www/analyzer/index.html | 29 +- www/analyzer/latest_checker.html.incl | 2 +- www/analyzer/potential_checkers.html | 183 +- www/analyzer/release_notes.html | 41 + www/analyzer/xcode.html | 44 +- www/comparison.html | 1 - www/compatibility.html | 101 +- www/cxx_status.html | 40 +- www/get_started.html | 14 +- www/hacking.html | 4 + www/menu.html.incl | 2 +- www/performance-2008-10-31.html | 132 - www/performance-2009-03-02.html | 110 - www/performance.html | 104 - 2321 files changed, 148484 insertions(+), 62284 deletions(-) create mode 100644 .arcconfig create mode 100644 CODE_OWNERS.TXT delete mode 100644 docs/AddressSanitizer.html create mode 100644 docs/AddressSanitizer.rst delete mode 100644 docs/AnalyzerRegions.html delete mode 100644 docs/AutomaticReferenceCounting.html create mode 100644 docs/AutomaticReferenceCounting.rst create mode 100644 docs/Block-ABI-Apple.rst create mode 100644 docs/BlockLanguageSpec.rst delete mode 100644 docs/BlockLanguageSpec.txt create mode 100644 docs/ClangCheck.rst create mode 100644 docs/ClangFormat.rst delete mode 100644 docs/ClangPlugins.html create mode 100644 docs/ClangPlugins.rst delete mode 100644 docs/ClangTools.html create mode 100644 docs/ClangTools.rst delete mode 100644 docs/DriverInternals.html create mode 100644 docs/DriverInternals.rst create mode 100644 docs/ExternalClangExamples.rst create mode 100644 docs/FAQ.rst delete mode 100644 docs/HowToSetupToolingForLLVM.html create mode 100644 docs/HowToSetupToolingForLLVM.rst delete mode 100644 docs/InternalsManual.html create mode 100644 docs/InternalsManual.rst delete mode 100644 docs/IntroductionToTheClangAST.html create mode 100644 docs/IntroductionToTheClangAST.rst delete mode 100644 docs/JSONCompilationDatabase.html create mode 100644 docs/JSONCompilationDatabase.rst delete mode 100644 docs/LanguageExtensions.html create mode 100644 docs/LanguageExtensions.rst delete mode 100644 docs/LibASTMatchers.html create mode 100644 docs/LibASTMatchers.rst create mode 100644 docs/LibASTMatchersTutorial.rst create mode 100644 docs/LibFormat.rst delete mode 100644 docs/LibTooling.html create mode 100644 docs/LibTooling.rst create mode 100644 docs/Makefile.sphinx create mode 100644 docs/MemorySanitizer.rst create mode 100644 docs/Modules.rst delete mode 100644 docs/ObjectiveCLiterals.html create mode 100644 docs/ObjectiveCLiterals.rst delete mode 100644 docs/PCHInternals.html create mode 100644 docs/PCHInternals.rst delete mode 100644 docs/PTHInternals.html create mode 100644 docs/PTHInternals.rst delete mode 100644 docs/RAVFrontendAction.html create mode 100644 docs/RAVFrontendAction.rst create mode 100644 docs/README.txt delete mode 100644 docs/ReleaseNotes.html create mode 100644 docs/ReleaseNotes.rst delete mode 100644 docs/ThreadSanitizer.html create mode 100644 docs/ThreadSanitizer.rst delete mode 100644 docs/Tooling.html create mode 100644 docs/Tooling.rst delete mode 100644 docs/UsersManual.html create mode 100644 docs/UsersManual.rst create mode 100644 docs/analyzer/DebugChecks.rst create mode 100644 docs/analyzer/Makefile create mode 100644 docs/analyzer/RegionStore.txt create mode 100644 docs/analyzer/conf.py delete mode 100644 docs/analyzer/debug-checks.txt create mode 100644 docs/analyzer/index.rst create mode 100644 docs/analyzer/make.bat create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 include/clang/AST/ASTTypeTraits.h create mode 100644 include/clang/AST/ASTUnresolvedSet.h create mode 100644 include/clang/AST/AttrIterator.h create mode 100644 include/clang/AST/CommentHTMLNamedCharacterReferences.td create mode 100644 include/clang/AST/DeclOpenMP.h delete mode 100644 include/clang/ASTMatchers/ASTTypeTraits.h create mode 100644 include/clang/Basic/CharInfo.h create mode 100644 include/clang/Basic/CommentOptions.h delete mode 100644 include/clang/Basic/ConvertUTF.h create mode 100644 include/clang/Basic/OpenMPKinds.def create mode 100644 include/clang/Basic/OpenMPKinds.h create mode 100644 include/clang/Basic/OperatorPrecedence.h create mode 100644 include/clang/Basic/TargetCXXABI.h create mode 100644 include/clang/Format/Format.h create mode 100644 include/clang/Lex/PPConditionalDirectiveRecord.h delete mode 100644 include/clang/Lex/PPMutationListener.h create mode 100644 include/clang/Serialization/GlobalModuleIndex.h create mode 100644 lib/ARCMigrate/TransProtectedScope.cpp create mode 100644 lib/AST/ASTDumper.cpp delete mode 100644 lib/AST/CommentDumper.cpp create mode 100644 lib/AST/DeclOpenMP.cpp delete mode 100644 lib/AST/StmtDumper.cpp create mode 100644 lib/Basic/CharInfo.cpp delete mode 100644 lib/Basic/ConvertUTF.c delete mode 100644 lib/Basic/ConvertUTFWrapper.cpp create mode 100644 lib/Basic/OpenMPKinds.cpp create mode 100644 lib/Basic/OperatorPrecedence.cpp create mode 100644 lib/CodeGen/CGAtomic.cpp create mode 100644 lib/Format/CMakeLists.txt create mode 100644 lib/Format/Format.cpp create mode 100644 lib/Format/Makefile create mode 100644 lib/Format/TokenAnnotator.cpp create mode 100644 lib/Format/TokenAnnotator.h create mode 100644 lib/Format/UnwrappedLineParser.cpp create mode 100644 lib/Format/UnwrappedLineParser.h create mode 100644 lib/Headers/prfchwintrin.h create mode 100644 lib/Headers/rdseedintrin.h create mode 100644 lib/Headers/stdnoreturn.h create mode 100644 lib/Lex/PPConditionalDirectiveRecord.cpp create mode 100644 lib/Lex/UnicodeCharSets.h create mode 100644 lib/Parse/ParseOpenMP.cpp create mode 100644 lib/Sema/SemaOpenMP.cpp create mode 100644 lib/Serialization/GlobalModuleIndex.cpp delete mode 100644 lib/StaticAnalyzer/Checkers/AttrNonNullChecker.cpp create mode 100644 lib/StaticAnalyzer/Checkers/NonNullParamChecker.cpp create mode 100644 test/ARCMT/block_copy_release.m create mode 100644 test/ARCMT/block_copy_release.m.result create mode 100644 test/ARCMT/check-with-pch.m create mode 100644 test/ARCMT/migrate-with-pch.m create mode 100644 test/ARCMT/objcmt-with-pch.m create mode 100644 test/ARCMT/objcmt-with-pch.m.result create mode 100644 test/ARCMT/protected-scope.m create mode 100644 test/ARCMT/protected-scope.m.result create mode 100644 test/Analysis/Inputs/system-header-simulator-for-malloc.h create mode 100644 test/Analysis/Malloc+MismatchedDeallocator+NewDelete.cpp create mode 100644 test/Analysis/Malloc+MismatchedDeallocator_intersections.cpp create mode 100644 test/Analysis/Malloc+NewDelete_intersections.cpp create mode 100644 test/Analysis/NSContainers.m create mode 100644 test/Analysis/NewDelete+MismatchedDeallocator_intersections.cpp create mode 100644 test/Analysis/NewDelete-checker-test.cpp create mode 100644 test/Analysis/NewDelete-custom.cpp create mode 100644 test/Analysis/NewDelete-intersections.mm create mode 100644 test/Analysis/NewDelete-path-notes.cpp create mode 100644 test/Analysis/NewDelete-variadic.cpp create mode 100644 test/Analysis/alloc-match-dealloc.mm create mode 100644 test/Analysis/call-invalidation.cpp create mode 100644 test/Analysis/cfg.cpp create mode 100644 test/Analysis/diagnostics/Inputs/include/sys/queue.h create mode 100644 test/Analysis/diagnostics/explicit-suppression.cpp create mode 100644 test/Analysis/diagnostics/false-positive-suppression.c create mode 100644 test/Analysis/diagnostics/no-prune-paths.c create mode 100644 test/Analysis/diagnostics/shortest-path-suppression.c create mode 100644 test/Analysis/global_region_invalidation.mm create mode 100644 test/Analysis/inlining/containers.cpp create mode 100644 test/Analysis/inlining/eager-reclamation-path-notes.cpp create mode 100644 test/Analysis/inlining/false-positive-suppression.cpp create mode 100644 test/Analysis/inlining/inline-defensive-checks.c create mode 100644 test/Analysis/inlining/inline-defensive-checks.cpp create mode 100644 test/Analysis/inlining/inline-defensive-checks.m create mode 100644 test/Analysis/inlining/path-notes.cpp create mode 100644 test/Analysis/objc/direct-ivar-assignment-in-annotated-functions.m create mode 100644 test/Analysis/reference.mm create mode 100644 test/Analysis/region-store.cpp create mode 100644 test/Analysis/retain-release-cf-audited.m create mode 100644 test/Analysis/shallow-mode.m create mode 100644 test/Analysis/superclass.m delete mode 100644 test/Analysis/viewcontroller.m create mode 100644 test/CXX/basic/basic.link/p6.cpp create mode 100644 test/CXX/basic/basic.start/basic.start.main/p2.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2a.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2b.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2c.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2d.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2e.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2f.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2g.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2h.cpp delete mode 100644 test/CXX/basic/basic.start/basic.start.main/p2i.cpp create mode 100644 test/CXX/dcl.dcl/dcl.attr/dcl.align/p5.cpp create mode 100644 test/CXX/dcl.dcl/dcl.attr/dcl.align/p6.cpp create mode 100644 test/CXX/dcl.dcl/dcl.attr/dcl.align/p7.cpp create mode 100644 test/CXX/dcl.dcl/dcl.attr/dcl.align/p8.cpp create mode 100644 test/CXX/dcl.dcl/dcl.attr/dcl.attr.depend/p1.cpp create mode 100644 test/CXX/dcl.dcl/dcl.attr/dcl.attr.depend/p2.cpp create mode 100644 test/CXX/dcl.dcl/dcl.attr/dcl.attr.noreturn/p1.cpp create mode 100644 test/CXX/dcl.decl/dcl.fct.def/dcl.fct.def.default/p1.cpp create mode 100644 test/CXX/special/class.copy/p12-0x.cpp create mode 100644 test/CXX/special/class.copy/p18-cxx11.cpp create mode 100644 test/CXX/special/class.copy/p25-0x.cpp create mode 100644 test/CXX/special/class.copy/p28-cxx11.cpp create mode 100644 test/CXX/special/class.inhctor/p1.cpp create mode 100644 test/CXX/special/class.inhctor/p2.cpp create mode 100644 test/CXX/special/class.inhctor/p4.cpp create mode 100644 test/CXX/special/class.inhctor/p8.cpp create mode 100644 test/CXX/temp/temp.decls/temp.variadic/p5.mm create mode 100644 test/CodeCompletion/constexpr.cpp create mode 100644 test/CodeGen/a5.c create mode 100644 test/CodeGen/aarch64-arguments.c create mode 100644 test/CodeGen/aarch64-inline-asm.c create mode 100644 test/CodeGen/aarch64-type-sizes.c create mode 100644 test/CodeGen/aarch64-varargs.c create mode 100644 test/CodeGen/arm-neon-fma.c create mode 100644 test/CodeGen/atomics-inlining.c create mode 100644 test/CodeGen/builtins-multiprecision.c create mode 100644 test/CodeGen/builtins-ppc.c create mode 100644 test/CodeGen/c11atomics-ios.c create mode 100644 test/CodeGen/c11atomics.c create mode 100644 test/CodeGen/code-coverage.c create mode 100644 test/CodeGen/complex-convert.c create mode 100644 test/CodeGen/compound-assign-overflow.c create mode 100644 test/CodeGen/debug-info-vector.c create mode 100644 test/CodeGen/fast-math.c create mode 100644 test/CodeGen/finite-math.c delete mode 100644 test/CodeGen/frame-pointer-elim.c create mode 100644 test/CodeGen/global-blocks-lines.c create mode 100644 test/CodeGen/incomplete-function-type-2.c create mode 100644 test/CodeGen/intel_ocl_bicc.c create mode 100644 test/CodeGen/libcalls-complex.c create mode 100644 test/CodeGen/lifetime2.c create mode 100644 test/CodeGen/mips-constraints-mem.c create mode 100644 test/CodeGen/mips-target-data.c create mode 100644 test/CodeGen/mips16-attr.c create mode 100644 test/CodeGen/ms-inline-asm.cpp create mode 100644 test/CodeGen/no-opt-volatile-memcpy.c create mode 100644 test/CodeGen/nvptx-cpus.c delete mode 100644 test/CodeGen/ppc-atomics.c create mode 100644 test/CodeGen/ppc64-complex-parms.c create mode 100644 test/CodeGen/ppc64-complex-return.c create mode 100644 test/CodeGen/ppc64-varargs-complex.c create mode 100644 test/CodeGen/prefetchw-builtins.c create mode 100644 test/CodeGen/r5.c create mode 100644 test/CodeGen/sanitize-init-order.cpp create mode 100644 test/CodeGen/sanitize-recover.c create mode 100644 test/CodeGen/sanitize-thread-attr.cpp create mode 100644 test/CodeGen/sanitize-use-after-scope.c create mode 100644 test/CodeGen/split-debug-filename.c create mode 100644 test/CodeGen/tbaa.cpp create mode 100644 test/CodeGen/ubsan-blacklist.c create mode 100644 test/CodeGen/ucn-identifiers.c create mode 100644 test/CodeGen/unsigned-overflow.c create mode 100644 test/CodeGen/unsigned-promotion.c create mode 100644 test/CodeGen/unsigned-trapv.c create mode 100644 test/CodeGen/x86_32-inline-asm.c create mode 100644 test/CodeGenCXX/aarch64-arguments.cpp create mode 100644 test/CodeGenCXX/aarch64-cxxabi.cpp create mode 100644 test/CodeGenCXX/bitfield.cpp create mode 100644 test/CodeGenCXX/bool-bitfield.cpp create mode 100644 test/CodeGenCXX/constructor-alias.cpp create mode 100644 test/CodeGenCXX/constructor-destructor-return-this.cpp create mode 100644 test/CodeGenCXX/coverage.cpp create mode 100644 test/CodeGenCXX/cp-blocks-linetables.cpp create mode 100644 test/CodeGenCXX/cxx11-noreturn.cpp create mode 100644 test/CodeGenCXX/cxx11-trivial-initializer-struct.cpp create mode 100644 test/CodeGenCXX/debug-info-same-line.cpp create mode 100644 test/CodeGenCXX/debug-info-static-member.cpp create mode 100644 test/CodeGenCXX/debug-info-union-template.cpp create mode 100644 test/CodeGenCXX/debug-info-zero-length-arrays.cpp create mode 100644 test/CodeGenCXX/dynamic-cast-hint.cpp create mode 100644 test/CodeGenCXX/exception-spec-decay.cpp create mode 100644 test/CodeGenCXX/mangle-ms-vector-types.cpp delete mode 100644 test/CodeGenCXX/microsoft-abi-constructors.cpp create mode 100755 test/CodeGenCXX/microsoft-abi-member-pointers.cpp create mode 100644 test/CodeGenCXX/microsoft-abi-structors.cpp create mode 100644 test/CodeGenCXX/microsoft-abi-vtables-single-inheritance.cpp create mode 100644 test/CodeGenCXX/no-opt-volatile-memcpy.cpp create mode 100644 test/CodeGenCXX/pod-member-memcpys.cpp create mode 100644 test/CodeGenCXX/pragma-weak.cpp create mode 100644 test/CodeGenCXX/runtimecc.cpp create mode 100644 test/CodeGenCXX/type_visibility.cpp create mode 100644 test/CodeGenCXX/visibility-ms-compat.cpp create mode 100644 test/CodeGenCXX/vtable-key-function-arm.cpp create mode 100644 test/CodeGenCXX/vtable-key-function-ios.cpp create mode 100644 test/CodeGenObjC/arc-captured-32bit-block-var-layout-2.m create mode 100644 test/CodeGenObjC/arc-loadweakretained-release.m create mode 100644 test/CodeGenObjC/arc-precise-lifetime.m create mode 100644 test/CodeGenObjC/arc-ternary-op.m create mode 100644 test/CodeGenObjC/arc-unoptimized-byref-var.m create mode 100644 test/CodeGenObjC/attr-exception.m create mode 100644 test/CodeGenObjC/block-byref-variable-layout.m create mode 100644 test/CodeGenObjC/debug-info-block-captured-self.m create mode 100644 test/CodeGenObjC/debug-info-block-line.m create mode 100644 test/CodeGenObjC/debug-info-id-with-protocol.m create mode 100644 test/CodeGenObjC/debug-info-ivars-extension.m create mode 100644 test/CodeGenObjC/debug-info-ivars-indirect.m create mode 100644 test/CodeGenObjC/debug-info-ivars-private.m create mode 100644 test/CodeGenObjC/extended-block-signature-encode.m create mode 100644 test/CodeGenObjC/externally-initialized-selectors.m create mode 100644 test/CodeGenObjC/ivar-invariant.m create mode 100644 test/CodeGenObjC/reorder-synthesized-ivars.m create mode 100644 test/CodeGenObjCXX/arc-attrs.mm create mode 100644 test/CodeGenObjCXX/arc-blocks.mm create mode 100644 test/CodeGenObjCXX/exceptions-legacy.mm create mode 100644 test/CodeGenObjCXX/externally-initialized-selectors.mm create mode 100644 test/CodeGenObjCXX/message.mm create mode 100644 test/CodeGenObjCXX/pr14474-gline-tables-only.mm create mode 100644 test/CodeGenObjCXX/unknown-anytype.mm create mode 100644 test/CodeGenOpenCL/addr-space-struct-arg.cl create mode 100644 test/CodeGenOpenCL/event_t.cl create mode 100644 test/CodeGenOpenCL/half.cl create mode 100644 test/CodeGenOpenCL/logical-ops.cl create mode 100644 test/CodeGenOpenCL/opencl_types.cl create mode 100644 test/CodeGenOpenCL/shifts.cl create mode 100644 test/CodeGenOpenCL/spir32_target.cl create mode 100644 test/CodeGenOpenCL/spir64_target.cl create mode 100644 test/Driver/Inputs/basic_linux_tree/usr/lib/gcc/x86_64-unknown-linux/4.6.0/crtbeginT.o create mode 100755 test/Driver/Inputs/hexagon_tree/gnu/bin/hexagon-as create mode 100755 test/Driver/Inputs/hexagon_tree/gnu/bin/hexagon-gcc create mode 100755 test/Driver/Inputs/hexagon_tree/gnu/bin/hexagon-ld create mode 100644 test/Driver/Inputs/hexagon_tree/gnu/hexagon/include/c++/4.4.0/ios create mode 100644 test/Driver/Inputs/hexagon_tree/gnu/hexagon/include/stdio.h create mode 100644 test/Driver/Inputs/hexagon_tree/gnu/lib/gcc/hexagon/4.4.0/include-fixed/limits.h create mode 100644 test/Driver/Inputs/hexagon_tree/gnu/lib/gcc/hexagon/4.4.0/include/stddef.h create mode 100644 test/Driver/Inputs/hexagon_tree/qc/bin/placeholder create mode 100644 test/Driver/Inputs/lit.local.cfg create mode 100644 test/Driver/Inputs/resource_dir/lib/linux/libclang_rt.asan-i386.a.syms create mode 100644 test/Driver/Inputs/resource_dir/lib/linux/libclang_rt.asan-x86_64.a.syms create mode 100644 test/Driver/Inputs/resource_dir/lib/linux/libclang_rt.msan-x86_64.a.syms create mode 100644 test/Driver/Inputs/resource_dir/lib/linux/libclang_rt.tsan-x86_64.a.syms create mode 100644 test/Driver/Inputs/resource_dir/lib/linux/libclang_rt.ubsan-i386.a.syms create mode 100644 test/Driver/Inputs/resource_dir/lib/linux/libclang_rt.ubsan-x86_64.a.syms create mode 100644 test/Driver/Inputs/resource_dir/lib/linux/libclang_rt.ubsan_cxx-i386.a.syms create mode 100644 test/Driver/Inputs/resource_dir/lib/linux/libclang_rt.ubsan_cxx-x86_64.a.syms create mode 100644 test/Driver/Inputs/ubuntu_13.04_multiarch_tree/lib/x86_64-linux-gnu/.keep create mode 100644 test/Driver/Inputs/ubuntu_13.04_multiarch_tree/usr/include/c++/4.7/backward/.keep create mode 100644 test/Driver/Inputs/ubuntu_13.04_multiarch_tree/usr/include/x86_64-linux-gnu/c++/4.7/.keep create mode 100644 test/Driver/Inputs/ubuntu_13.04_multiarch_tree/usr/include/x86_64-linux-gnu/c++/4.7/32/.keep create mode 100644 test/Driver/Inputs/ubuntu_13.04_multiarch_tree/usr/lib/gcc/x86_64-linux-gnu/4.7/32/.keep create mode 100644 test/Driver/Inputs/ubuntu_13.04_multiarch_tree/usr/lib/gcc/x86_64-linux-gnu/4.7/32/crtbegin.o create mode 100644 test/Driver/Inputs/ubuntu_13.04_multiarch_tree/usr/lib/gcc/x86_64-linux-gnu/4.7/crtbegin.o create mode 100644 test/Driver/aarch64-features.c delete mode 100644 test/Driver/altivec.cpp create mode 100644 test/Driver/arm-cortex-cpus.c delete mode 100644 test/Driver/asan-ld.c create mode 100644 test/Driver/claim-unused.c create mode 100644 test/Driver/darwin-sanitizer-ld.c create mode 100644 test/Driver/debug-comp-dir.S create mode 100644 test/Driver/debug-main-file.S create mode 100644 test/Driver/fcomment-block-commands.c create mode 100644 test/Driver/frame-pointer-elim.c create mode 100644 test/Driver/fsanitize-blacklist.c create mode 100644 test/Driver/hexagon-toolchain-elf.c create mode 100644 test/Driver/hexagon-toolchain.c create mode 100644 test/Driver/inhibit-downstream-commands.c create mode 100644 test/Driver/integrated-as.c create mode 100644 test/Driver/integrated-as.s create mode 100644 test/Driver/lit.local.cfg create mode 100644 test/Driver/mips-eleb.c create mode 100644 test/Driver/mips-long-double.c create mode 100644 test/Driver/modules_integrated_as.c create mode 100644 test/Driver/ms-inline-asm.c create mode 100644 test/Driver/no-integrated-as-win.c create mode 100644 test/Driver/objc_default_synth.m create mode 100644 test/Driver/output-file-is-dir.c create mode 100644 test/Driver/ppc-features.cpp create mode 100644 test/Driver/r600-mcpu.cl create mode 100644 test/Driver/sanitizer-ld.c create mode 100644 test/Driver/split-debug.c create mode 100644 test/Driver/target-as.s delete mode 100644 test/Driver/ubsan-ld.c create mode 100644 test/Driver/visibility.cpp create mode 100644 test/FixIt/auto-isa-fixit.m create mode 100644 test/FixIt/bridge-cast-in-arc.mm create mode 100644 test/FixIt/bridge-in-non-arc.m create mode 100644 test/FixIt/fixit-cxx11-attributes.cpp create mode 100644 test/FixIt/fixit-newline-style.c create mode 100644 test/FixIt/fixit-nsstring-compare.m create mode 100644 test/FixIt/format.mm create mode 100644 test/Format/basic.cpp create mode 100644 test/Format/diagnostic.cpp create mode 100644 test/Format/ranges.cpp create mode 100644 test/Frontend/ast-main.cpp create mode 100644 test/Frontend/dependency-gen-escaping.c create mode 100644 test/Frontend/hexagon-target-basic.c create mode 100644 test/Frontend/warning-options.cpp create mode 100644 test/Headers/c11.c create mode 100644 test/Headers/cxx11.cpp create mode 100644 test/Index/Inputs/CommentXML/invalid-para-kind-01.xml create mode 100644 test/Index/Inputs/CommentXML/invalid-para-kind-02.xml create mode 100644 test/Index/Inputs/CommentXML/valid-para-kind-01.xml create mode 100644 test/Index/annotate-comments-property-accessor.m create mode 100644 test/Index/annotate-comments-typedef.m create mode 100644 test/Index/codecompletion-chained.cpp create mode 100644 test/Index/comment-c-decls.c create mode 100644 test/Index/comment-cplus-decls.cpp create mode 100644 test/Index/comment-cplus-template-decls.cpp create mode 100644 test/Index/comment-custom-block-command.cpp create mode 100644 test/Index/comment-objc-decls.m create mode 100644 test/Index/comment-to-html-xml-conversion.cpp create mode 100644 test/Index/complete-documentation-properties.m delete mode 100644 test/Index/complete-driver-errors.c create mode 100644 test/Index/file-includes.c create mode 100644 test/Index/fix-its.m create mode 100644 test/Index/format-comment-cdecls.c create mode 100644 test/Index/getcursor-preamble.h create mode 100644 test/Index/getcursor-preamble.m create mode 100644 test/Index/headerfile-comment-to-html.m create mode 100644 test/Index/modules-objc-categories.m create mode 100644 test/Index/print-bitwidth.c create mode 100644 test/Index/print-type.c create mode 100644 test/Index/print-type.cpp create mode 100644 test/Index/print-type.m delete mode 100644 test/Index/print-typekind.c delete mode 100644 test/Index/print-typekind.m create mode 100644 test/Index/skip-parsed-bodies/compile_commands.json create mode 100644 test/Index/skip-parsed-bodies/imported.h create mode 100644 test/Index/skip-parsed-bodies/lit.local.cfg create mode 100644 test/Index/skip-parsed-bodies/pragma_once.h create mode 100644 test/Index/skip-parsed-bodies/t.h create mode 100644 test/Index/skip-parsed-bodies/t1.cpp create mode 100644 test/Index/skip-parsed-bodies/t2.cpp create mode 100644 test/Index/skip-parsed-bodies/t3.cpp delete mode 100644 test/Index/vector-types.c create mode 100644 test/Lexer/builtin_redef.c create mode 100644 test/Lexer/cxx0x_raw_string_directives.cpp create mode 100644 test/Lexer/has_feature_memory_sanitizer.cpp create mode 100644 test/Lexer/has_feature_thread_sanitizer.cpp create mode 100644 test/Lexer/pragma-region.c delete mode 100644 test/Lexer/token-concat-2.c create mode 100644 test/Lexer/unicode-strings.c create mode 100644 test/Lexer/unicode.c create mode 100644 test/Lexer/utf8-invalid.c create mode 100644 test/Misc/ast-dump-attr.cpp create mode 100644 test/Misc/ast-dump-color.cpp create mode 100644 test/Misc/ast-dump-comment.cpp create mode 100644 test/Misc/ast-dump-decl.c create mode 100644 test/Misc/ast-dump-decl.cpp create mode 100644 test/Misc/ast-dump-decl.m create mode 100644 test/Misc/ast-dump-decl.mm create mode 100644 test/Misc/ast-dump-stmt.cpp create mode 100644 test/Misc/dev-fd-fs.c create mode 100644 test/Misc/diag-presumed.c create mode 100644 test/Misc/diag-template-diffing-cxx98.cpp create mode 100644 test/Misc/diagnostic-crash.cpp create mode 100644 test/Misc/freebsd-arm-size_t.c create mode 100644 test/Misc/serialized-diags.m create mode 100644 test/Modules/Inputs/Conflicts/conflict_a.h create mode 100644 test/Modules/Inputs/Conflicts/conflict_b.h create mode 100644 test/Modules/Inputs/Conflicts/module.map create mode 100644 test/Modules/Inputs/DependsOnModule.framework/DependsOnModule create mode 100644 test/Modules/Inputs/HasSubModules.framework/Frameworks/Sub.framework/Headers/Sub.h create mode 100644 test/Modules/Inputs/HasSubModules.framework/Frameworks/Sub.framework/Headers/Types.h create mode 100644 test/Modules/Inputs/HasSubModules.framework/Frameworks/Sub.framework/PrivateHeaders/SubPriv.h create mode 100644 test/Modules/Inputs/HasSubModules.framework/Headers/HasSubModules.h create mode 100644 test/Modules/Inputs/HasSubModules.framework/PrivateHeaders/HasSubModulesPriv.h create mode 100644 test/Modules/Inputs/MethodPoolASub.h create mode 100644 test/Modules/Inputs/MethodPoolASub2.h create mode 100644 test/Modules/Inputs/MethodPoolBSub.h create mode 100644 test/Modules/Inputs/Module.framework/Module create mode 100644 test/Modules/Inputs/NoUmbrella.framework/NoUmbrella create mode 100644 test/Modules/Inputs/StdDef/module.map create mode 100644 test/Modules/Inputs/StdDef/other.h create mode 100644 test/Modules/Inputs/StdDef/size_t.h create mode 100644 test/Modules/Inputs/autolink-sub.h create mode 100644 test/Modules/Inputs/autolink-sub2.h create mode 100644 test/Modules/Inputs/autolink.h create mode 100644 test/Modules/Inputs/builtin.h create mode 100644 test/Modules/Inputs/builtin_sub.h create mode 100644 test/Modules/Inputs/category_left_sub.h create mode 100644 test/Modules/Inputs/category_right_sub.h create mode 100644 test/Modules/Inputs/config.h create mode 100644 test/Modules/Inputs/cxx-inline-namespace.h create mode 100644 test/Modules/Inputs/cxx-linkage-cache.h create mode 100644 test/Modules/Inputs/cxx-many-overloads.h create mode 100644 test/Modules/Inputs/diag_pragma.h create mode 100644 test/Modules/Inputs/ignored_macros.h create mode 100644 test/Modules/Inputs/linkage-merge-bar.h create mode 100644 test/Modules/Inputs/linkage-merge-foo.h create mode 100644 test/Modules/Inputs/linkage-merge-sub.h create mode 100644 test/Modules/Inputs/oldname/module.map create mode 100644 test/Modules/Inputs/oldname/new_name.h create mode 100644 test/Modules/Inputs/redecl-merge-bottom-prefix.h create mode 100644 test/Modules/Inputs/weird_objc.h create mode 100644 test/Modules/autolink.m create mode 100644 test/Modules/build-fail-notes.m create mode 100644 test/Modules/builtins.m create mode 100644 test/Modules/config_macros.m create mode 100644 test/Modules/conflicts.m create mode 100644 test/Modules/cxx-inline-namespace.cpp create mode 100644 test/Modules/cxx-linkage-cache.cpp create mode 100644 test/Modules/cxx-many-overloads.cpp create mode 100644 test/Modules/decldef.m create mode 100644 test/Modules/diag-pragma.c create mode 100644 test/Modules/epic-fail.m create mode 100644 test/Modules/global_index.m create mode 100644 test/Modules/ignored_macros.m create mode 100644 test/Modules/linkage-merge.cpp create mode 100644 test/Modules/linkage-merge.m create mode 100644 test/Modules/module_file_info.m create mode 100644 test/Modules/objc_redef.m delete mode 100644 test/Modules/on-demand-build-warnings.m create mode 100644 test/Modules/prune.m create mode 100644 test/Modules/redecl-merge2.m create mode 100644 test/Modules/renamed.m create mode 100644 test/Modules/stddef.m create mode 100644 test/OpenMP/linking.c create mode 100644 test/OpenMP/no_option.c create mode 100644 test/OpenMP/no_option_no_warn.c create mode 100644 test/OpenMP/openmp_common.c create mode 100644 test/OpenMP/option_warn.c create mode 100644 test/OpenMP/predefined_macro.c create mode 100644 test/OpenMP/threadprivate_ast_print.cpp create mode 100644 test/OpenMP/threadprivate_messages.cpp create mode 100644 test/PCH/crash-12631281.cpp create mode 100644 test/PCH/floating-literal.c create mode 100644 test/PCH/irgen-rdar13114142.mm create mode 100644 test/PCH/macro-redef.c create mode 100644 test/PCH/multiple-include-pch.c create mode 100644 test/PCH/ocl_types.cl create mode 100644 test/PCH/ocl_types.h create mode 100644 test/PCH/thread-safety-attrs.cpp create mode 100644 test/PCH/undefined-internal.c create mode 100644 test/Parser/atomic.c create mode 100644 test/Parser/attributes.mm create mode 100644 test/Parser/c11-noreturn.c create mode 100644 test/Parser/crash-report.c create mode 100644 test/Parser/cxx11-base-spec-attributes.cpp create mode 100644 test/Parser/missing-closing-rbrace.m create mode 100644 test/Parser/objcxx11-protocol-in-template.mm delete mode 100644 test/Parser/prefix-attributes.m create mode 100644 test/Parser/warn-semicolon-before-method-body.m create mode 100644 test/Preprocessor/aarch64-target-features.c create mode 100644 test/Preprocessor/first-line-indent.c create mode 100644 test/Preprocessor/invalid-__has_warning1.c create mode 100644 test/Preprocessor/invalid-__has_warning2.c create mode 100644 test/Preprocessor/iwithprefix.c delete mode 100644 test/Preprocessor/macro-multiline.c create mode 100644 test/Preprocessor/macro-multiline.c.ignoreme create mode 100644 test/Preprocessor/macro_arg_slocentry_merge.c create mode 100644 test/Preprocessor/macro_arg_slocentry_merge.h delete mode 100644 test/Preprocessor/macro_expandloc2.c create mode 100644 test/Preprocessor/macro_variadic.cl delete mode 100644 test/Preprocessor/output_paste_avoid.c create mode 100644 test/Preprocessor/output_paste_avoid.cpp create mode 100644 test/Preprocessor/print_line_include.c create mode 100644 test/Preprocessor/print_line_include.h delete mode 100644 test/Preprocessor/stringize_space2.c create mode 100644 test/Preprocessor/ucn-allowed-chars.c create mode 100644 test/Preprocessor/ucn-pp-identifier.c create mode 100644 test/Preprocessor/utf8-allowed-chars.c create mode 100644 test/Rewriter/line-generation-test.m create mode 100644 test/Rewriter/modern-write-bf-abi.mm create mode 100644 test/Rewriter/objc-modern-property-bitfield.m create mode 100644 test/Rewriter/rewrite-line-directive.m create mode 100644 test/Rewriter/rewrite-modern-qualified-type.mm create mode 100644 test/Sema/attr-print.c create mode 100644 test/Sema/implicit-cast-dump.c create mode 100644 test/Sema/invalid-cast.cpp create mode 100644 test/Sema/memset-invalid-1.c create mode 100644 test/Sema/mips16_attr_allowed.c create mode 100644 test/Sema/mips16_attr_not_allowed.c create mode 100644 test/Sema/ms-inline-asm-invalid-arch.c create mode 100644 test/Sema/nowarn-documentation-property.m create mode 100644 test/Sema/pid_t.c create mode 100644 test/Sema/ppc-bool.c create mode 100644 test/Sema/switch-1.c create mode 100644 test/Sema/ucn-identifiers.c create mode 100644 test/Sema/uninit-det-order.c create mode 100644 test/Sema/varargs_unreachable.c create mode 100644 test/Sema/variadic-promotion.c create mode 100644 test/Sema/warn-documentation-crlf.c create mode 100644 test/Sema/warn-duplicate-enum.c create mode 100644 test/Sema/warn-main-return-type.c create mode 100644 test/Sema/warn-main.c create mode 100644 test/Sema/warn-sizeof-array-decay.c create mode 100644 test/Sema/warn-unused-variables-werror.c create mode 100644 test/Sema/warn-vla.c create mode 100644 test/SemaCXX/address-space-initialize.cpp create mode 100644 test/SemaCXX/attr-no-sanitize-address.cpp create mode 100644 test/SemaCXX/attr-no-sanitize-memory.cpp create mode 100644 test/SemaCXX/attr-no-sanitize-thread.cpp create mode 100644 test/SemaCXX/attr-print.cpp create mode 100644 test/SemaCXX/auto-pragma.cpp create mode 100644 test/SemaCXX/c99-variable-length-array-cxx11.cpp create mode 100644 test/SemaCXX/crash-lambda-12645424.cpp create mode 100644 test/SemaCXX/cxx11-attr-print.cpp create mode 100644 test/SemaCXX/cxx11-gnu-attrs.cpp create mode 100644 test/SemaCXX/decl-microsoft-call-conv.cpp delete mode 100644 test/SemaCXX/default-arg-special-member.cpp create mode 100644 test/SemaCXX/extern-c.cpp create mode 100644 test/SemaCXX/linkage2.cpp create mode 100644 test/SemaCXX/pragma-weak.cpp delete mode 100644 test/SemaCXX/qualified-names-print.cpp create mode 100644 test/SemaCXX/undefined-inline.cpp create mode 100644 test/SemaCXX/virtual-override-x64.cpp create mode 100644 test/SemaCXX/virtual-override-x86.cpp create mode 100644 test/SemaCXX/visibility.cpp create mode 100644 test/SemaCXX/warn-func-not-needed.cpp create mode 100644 test/SemaCXX/warn-reinterpret-base-class.cpp create mode 100644 test/SemaCXX/warn-static-const-float.cpp create mode 100644 test/SemaCXX/warn-unsequenced.cpp create mode 100644 test/SemaCXX/warn-variable-not-needed.cpp create mode 100644 test/SemaCXX/warn-vla.cpp delete mode 100644 test/SemaObjC/boxing-illegal-types.m create mode 100644 test/SemaObjC/boxing-illegal.m create mode 100644 test/SemaObjC/error-outof-scope-property-use.m create mode 100644 test/SemaObjC/forward-protocol-incomplete-impl-warn.m create mode 100644 test/SemaObjC/generic-selection.m create mode 100644 test/SemaObjC/property-noninherited-availability-attr.m create mode 100644 test/SemaObjC/typo-correction.m create mode 100644 test/SemaObjCXX/capturing-flexible-array-in-block.mm create mode 100644 test/SemaObjCXX/instancetype.mm create mode 100644 test/SemaOpenCL/endian-attr.cl create mode 100644 test/SemaOpenCL/event_t.cl create mode 100644 test/SemaOpenCL/event_t_overload.cl create mode 100644 test/SemaOpenCL/half.cl create mode 100644 test/SemaOpenCL/invalid-kernel-attrs.cl create mode 100644 test/SemaOpenCL/invalid-kernel.cl create mode 100644 test/SemaOpenCL/invalid-logical-ops-1.1.cl create mode 100644 test/SemaOpenCL/invalid-logical-ops-1.2.cl create mode 100644 test/SemaOpenCL/sampler_t.cl create mode 100644 test/SemaOpenCL/sampler_t_overload.cl create mode 100644 test/SemaOpenCL/shifts.cl create mode 100644 test/SemaOpenCL/unsupported.cl create mode 100644 test/SemaTemplate/alignas.cpp create mode 100644 test/SemaTemplate/temp_arg_nontype_cxx11.cpp create mode 100644 test/TableGen/DiagnosticBase.inc create mode 100644 test/TableGen/anonymous-groups.td create mode 100644 test/TableGen/lit.local.cfg create mode 100644 test/TableGen/tg-fixits.td create mode 100644 tools/clang-format/CMakeLists.txt create mode 100644 tools/clang-format/ClangFormat.cpp create mode 100644 tools/clang-format/Makefile create mode 100755 tools/clang-format/clang-format-diff.py create mode 100644 tools/clang-format/clang-format.py create mode 100644 tools/libclang/CLog.h create mode 100644 tools/libclang/SimpleFormatContext.h create mode 100644 unittests/AST/ASTContextParentMapTest.cpp create mode 100644 unittests/AST/MatchVerifier.h create mode 100644 unittests/Basic/CharInfoTest.cpp create mode 100644 unittests/Format/CMakeLists.txt create mode 100644 unittests/Format/FormatTest.cpp create mode 100644 unittests/Format/Makefile create mode 100644 unittests/Lex/PPConditionalDirectiveRecordTest.cpp delete mode 100644 unittests/Lex/PreprocessingRecordTest.cpp delete mode 100644 utils/C++Tests/Clang-Code-Compile/lit.local.cfg delete mode 100644 utils/C++Tests/Clang-Code-Syntax/lit.local.cfg delete mode 100644 utils/C++Tests/Clang-Syntax/lit.local.cfg delete mode 100644 utils/C++Tests/LLVM-Code-Compile/lit.local.cfg delete mode 100755 utils/C++Tests/LLVM-Code-Symbols/check-symbols delete mode 100644 utils/C++Tests/LLVM-Code-Symbols/lit.local.cfg delete mode 100644 utils/C++Tests/LLVM-Code-Syntax/lit.local.cfg delete mode 100644 utils/C++Tests/LLVM-Syntax/lit.local.cfg delete mode 100644 utils/C++Tests/lit.cfg delete mode 100644 utils/C++Tests/stdc++-Syntax/lit.local.cfg delete mode 100644 utils/OptionalTests/Extra/README.txt delete mode 100644 utils/OptionalTests/Extra/Runtime/darwin-clang_rt.c delete mode 100644 utils/OptionalTests/README.txt delete mode 100644 utils/OptionalTests/lit.cfg delete mode 100755 utils/SummarizeErrors create mode 100644 utils/TableGen/ClangCommentHTMLNamedCharacterReferenceEmitter.cpp delete mode 100644 www/performance-2008-10-31.html delete mode 100644 www/performance-2009-03-02.html delete mode 100644 www/performance.html diff --git a/.arcconfig b/.arcconfig new file mode 100644 index 000000000000..7f45342a433a --- /dev/null +++ b/.arcconfig @@ -0,0 +1,4 @@ +{ + "project_id" : "clang", + "conduit_uri" : "http://llvm-reviews.chandlerc.com/" +} diff --git a/.gitignore b/.gitignore index 6be9976262a8..6c34e37f4cb6 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,6 @@ cscope.out #==============================================================================# # Clang extra user tools, which is tracked independently (clang-tools-extra). tools/extra +# Sphinx build products +docs/_build +docs/analyzer/_build diff --git a/CMakeLists.txt b/CMakeLists.txt index 53d4165caec3..6efcd4a7bda8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -66,6 +66,11 @@ if( CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR ) set( CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib ) set( CLANG_BUILT_STANDALONE 1 ) + + find_package(LibXml2) + if (LIBXML2_FOUND) + set(CLANG_HAVE_LIBXML 1) + endif () endif() set(CLANG_RESOURCE_DIR "" CACHE STRING @@ -133,16 +138,17 @@ configure_file( # Add appropriate flags for GCC if (LLVM_COMPILER_IS_GCC_COMPATIBLE) set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-common -Woverloaded-virtual -Wcast-qual -fno-strict-aliasing -pedantic -Wno-long-long -Wall -W -Wno-unused-parameter -Wwrite-strings") + + check_cxx_compiler_flag("-Werror -Wnested-anon-types" CXX_SUPPORTS_NO_NESTED_ANON_TYPES_FLAG) + if( CXX_SUPPORTS_NO_NESTED_ANON_TYPES_FLAG ) + set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-nested-anon-types" ) + endif() endif () if (APPLE) set(CMAKE_MODULE_LINKER_FLAGS "-Wl,-flat_namespace -Wl,-undefined -Wl,suppress") endif () -# libxml2 is an optional dependency, required only to run validation -# tests on XML output. -find_package(LibXml2) - configure_file( ${CLANG_SOURCE_DIR}/include/clang/Config/config.h.cmake ${CLANG_BINARY_DIR}/include/clang/Config/config.h) @@ -253,6 +259,9 @@ install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/include/ add_definitions( -D_GNU_SOURCE ) +# FIXME: They should be options. +add_definitions(-DCLANG_ENABLE_ARCMT -DCLANG_ENABLE_REWRITER -DCLANG_ENABLE_STATIC_ANALYZER) + # Clang version information set(CLANG_EXECUTABLE_VERSION "${CLANG_VERSION_MAJOR}.${CLANG_VERSION_MINOR}" CACHE STRING @@ -272,13 +281,15 @@ add_subdirectory(runtime) option(CLANG_BUILD_EXAMPLES "Build CLANG example programs by default." OFF) add_subdirectory(examples) +option(CLANG_INCLUDE_TESTS + "Generate build targets for the Clang unit tests." + ${LLVM_INCLUDE_TESTS}) + # TODO: docs. add_subdirectory(test) -if( LLVM_INCLUDE_TESTS ) - if( NOT CLANG_BUILT_STANDALONE ) - add_subdirectory(unittests) - endif() +if( CLANG_INCLUDE_TESTS ) + add_subdirectory(unittests) endif() # Workaround for MSVS10 to avoid the Dialog Hell diff --git a/CODE_OWNERS.TXT b/CODE_OWNERS.TXT new file mode 100644 index 000000000000..13c0a9bde665 --- /dev/null +++ b/CODE_OWNERS.TXT @@ -0,0 +1,40 @@ +This file is a list of the people responsible for ensuring that patches for a +particular part of Clang are reviewed, either by themself or by someone else. +They are also the gatekeepers for their part of Clang, with the final word on +what goes in or not. + +The list is sorted by surname and formatted to allow easy grepping and +beautification by scripts. The fields are: name (N), email (E), web-address +(W), PGP key ID and fingerprint (P), description (D), and snail-mail address +(S). + +N: Chandler Carruth +E: chandlerc@gmail.com +E: chandlerc@google.com +D: CMake, library layering + +N: Eric Christopher +E: echristo@gmail.com +D: Debug Information, autotools/configure/make build, inline assembly + +N: Doug Gregor +D: All parts of Clang not covered by someone else + +N: Anton Korobeynikov +E: anton@korobeynikov.info +D: Exception handling, Windows codegen, ARM EABI + +N: Ted Kremenek +D: Clang Static Analyzer + +N: John McCall +E: rjmccall@apple.com +D: Clang LLVM IR generation + +N: Chad Rosier +E: mcrosier@apple.com +D: MS-inline asm, and the compiler driver + +N: Richard Smith +E: richard@metafoo.co.uk +D: Clang Semantic Analysis (tools/clang/lib/Sema/* tools/clang/include/clang/Sema/*) diff --git a/INSTALL.txt b/INSTALL.txt index e8e320962bb4..bd2f4fe37096 100644 --- a/INSTALL.txt +++ b/INSTALL.txt @@ -44,6 +44,6 @@ From inside the Clang build directory, run 'make install' to install the Clang compiler and header files into the prefix directory selected when LLVM was configured. -The Clang compiler is available as 'clang' and supports a gcc like command line +The Clang compiler is available as 'clang' and 'clang++'. It supports a gcc like command line interface. See the man page for clang (installed into $prefix/share/man/man1) for more information. diff --git a/LICENSE.TXT b/LICENSE.TXT index 6c224f84c5bb..e31223a486aa 100644 --- a/LICENSE.TXT +++ b/LICENSE.TXT @@ -4,7 +4,7 @@ LLVM Release License University of Illinois/NCSA Open Source License -Copyright (c) 2007-2012 University of Illinois at Urbana-Champaign. +Copyright (c) 2007-2013 University of Illinois at Urbana-Champaign. All rights reserved. Developed by: diff --git a/NOTES.txt b/NOTES.txt index 1c89d685729b..107ec5ad48c5 100644 --- a/NOTES.txt +++ b/NOTES.txt @@ -2,9 +2,6 @@ // Random Notes //===---------------------------------------------------------------------===// -C90/C99/C++ Comparisons: -http://david.tribble.com/text/cdiffs.htm - //===---------------------------------------------------------------------===// To time GCC preprocessing speed without output, use: diff --git a/bindings/python/clang/cindex.py b/bindings/python/clang/cindex.py index 5e162c0e8349..70f4f36a2cfd 100644 --- a/bindings/python/clang/cindex.py +++ b/bindings/python/clang/cindex.py @@ -1271,6 +1271,17 @@ class Cursor(Structure): # created. return self._tu + @property + def referenced(self): + """ + For a cursor that is a reference, returns a cursor + representing the entity that it references. + """ + if not hasattr(self, '_referenced'): + self._referenced = conf.lib.clang_getCursorReferenced(self) + + return self._referenced + def get_arguments(self): """Return an iterator for accessing the arguments of this cursor.""" num_args = conf.lib.clang_Cursor_getNumArguments(self) @@ -1634,6 +1645,33 @@ class _CXUnsavedFile(Structure): """Helper for passing unsaved file arguments.""" _fields_ = [("name", c_char_p), ("contents", c_char_p), ('length', c_ulong)] +# Functions calls through the python interface are rather slow. Fortunately, +# for most symboles, we do not need to perform a function call. Their spelling +# never changes and is consequently provided by this spelling cache. +SpellingCache = { + # 0: CompletionChunk.Kind("Optional"), + # 1: CompletionChunk.Kind("TypedText"), + # 2: CompletionChunk.Kind("Text"), + # 3: CompletionChunk.Kind("Placeholder"), + # 4: CompletionChunk.Kind("Informative"), + # 5 : CompletionChunk.Kind("CurrentParameter"), + 6: '(', # CompletionChunk.Kind("LeftParen"), + 7: ')', # CompletionChunk.Kind("RightParen"), + 8: ']', # CompletionChunk.Kind("LeftBracket"), + 9: ']', # CompletionChunk.Kind("RightBracket"), + 10: '{', # CompletionChunk.Kind("LeftBrace"), + 11: '}', # CompletionChunk.Kind("RightBrace"), + 12: '<', # CompletionChunk.Kind("LeftAngle"), + 13: '>', # CompletionChunk.Kind("RightAngle"), + 14: ', ', # CompletionChunk.Kind("Comma"), + # 15: CompletionChunk.Kind("ResultType"), + 16: ':', # CompletionChunk.Kind("Colon"), + 17: ';', # CompletionChunk.Kind("SemiColon"), + 18: '=', # CompletionChunk.Kind("Equal"), + 19: ' ', # CompletionChunk.Kind("HorizontalSpace"), + # 20: CompletionChunk.Kind("VerticalSpace") +} + class CompletionChunk: class Kind: def __init__(self, name): @@ -1648,18 +1686,30 @@ class CompletionChunk: def __init__(self, completionString, key): self.cs = completionString self.key = key + self.__kindNumberCache = -1 def __repr__(self): return "{'" + self.spelling + "', " + str(self.kind) + "}" @CachedProperty def spelling(self): + if self.__kindNumber in SpellingCache: + return SpellingCache[self.__kindNumber] return conf.lib.clang_getCompletionChunkText(self.cs, self.key).spelling + # We do not use @CachedProperty here, as the manual implementation is + # apparently still significantly faster. Please profile carefully if you + # would like to add CachedProperty back. + @property + def __kindNumber(self): + if self.__kindNumberCache == -1: + self.__kindNumberCache = \ + conf.lib.clang_getCompletionChunkKind(self.cs, self.key) + return self.__kindNumberCache + @CachedProperty def kind(self): - res = conf.lib.clang_getCompletionChunkKind(self.cs, self.key) - return completionChunkKindMap[res] + return completionChunkKindMap[self.__kindNumber] @CachedProperty def string(self): @@ -1672,19 +1722,19 @@ class CompletionChunk: None def isKindOptional(self): - return self.kind == completionChunkKindMap[0] + return self.__kindNumber == 0 def isKindTypedText(self): - return self.kind == completionChunkKindMap[1] + return self.__kindNumber == 1 def isKindPlaceHolder(self): - return self.kind == completionChunkKindMap[3] + return self.__kindNumber == 3 def isKindInformative(self): - return self.kind == completionChunkKindMap[4] + return self.__kindNumber == 4 def isKindResultType(self): - return self.kind == completionChunkKindMap[15] + return self.__kindNumber == 15 completionChunkKindMap = { 0: CompletionChunk.Kind("Optional"), @@ -1965,7 +2015,7 @@ class TranslationUnit(ClangObject): len(args), unsaved_array, len(unsaved_files), options) - if ptr is None: + if not ptr: raise TranslationUnitLoadError("Error parsing translation unit.") return cls(ptr, index=index) @@ -1987,7 +2037,7 @@ class TranslationUnit(ClangObject): index = Index.create() ptr = conf.lib.clang_createTranslationUnit(index, filename) - if ptr is None: + if not ptr: raise TranslationUnitLoadError(filename) return cls(ptr=ptr, index=index) @@ -3046,13 +3096,13 @@ class Config: Config.library_path = path @staticmethod - def set_library_file(file): - """Set the exact location of libclang from""" + def set_library_file(filename): + """Set the exact location of libclang""" if Config.loaded: raise Exception("library file must be set before before using " \ "any other functionalities in libclang.") - Config.library_file = path + Config.library_file = filename @staticmethod def set_compatibility_check(check_status): diff --git a/bindings/python/tests/cindex/test_cursor.py b/bindings/python/tests/cindex/test_cursor.py index edb209b52b96..a27525cfe553 100644 --- a/bindings/python/tests/cindex/test_cursor.py +++ b/bindings/python/tests/cindex/test_cursor.py @@ -250,3 +250,12 @@ def test_get_arguments(): assert len(arguments) == 2 assert arguments[0].spelling == "i" assert arguments[1].spelling == "j" + +def test_referenced(): + tu = get_tu('void foo(); void bar() { foo(); }') + foo = get_cursor(tu, 'foo') + bar = get_cursor(tu, 'bar') + for c in bar.get_children(): + if c.kind == CursorKind.CALL_EXPR: + assert c.referenced.spelling == foo.spelling + break diff --git a/bindings/python/tests/cindex/test_translation_unit.py b/bindings/python/tests/cindex/test_translation_unit.py index c91f126097ac..f77998e52457 100644 --- a/bindings/python/tests/cindex/test_translation_unit.py +++ b/bindings/python/tests/cindex/test_translation_unit.py @@ -8,6 +8,7 @@ from clang.cindex import Index from clang.cindex import SourceLocation from clang.cindex import SourceRange from clang.cindex import TranslationUnitSaveError +from clang.cindex import TranslationUnitLoadError from clang.cindex import TranslationUnit from .util import get_cursor from .util import get_tu @@ -239,3 +240,19 @@ def test_get_tokens_gc(): del tokens gc.collect() gc.collect() # Just in case. + +def test_fail_from_source(): + path = os.path.join(kInputsDir, 'non-existent.cpp') + try: + tu = TranslationUnit.from_source(path) + except TranslationUnitLoadError: + tu = None + assert tu == None + +def test_fail_from_ast_file(): + path = os.path.join(kInputsDir, 'non-existent.ast') + try: + tu = TranslationUnit.from_ast_file(path) + except TranslationUnitLoadError: + tu = None + assert tu == None diff --git a/bindings/xml/comment-xml-schema.rng b/bindings/xml/comment-xml-schema.rng index d98f405cf9e7..22371dfed1e4 100644 --- a/bindings/xml/comment-xml-schema.rng +++ b/bindings/xml/comment-xml-schema.rng @@ -24,6 +24,9 @@ + + + @@ -73,6 +76,9 @@ + + + @@ -120,6 +126,9 @@ + + + @@ -152,6 +161,9 @@ + + + @@ -185,6 +197,9 @@ + + + @@ -218,6 +233,9 @@ + + + @@ -251,6 +269,9 @@ + + + @@ -329,6 +350,14 @@ + + + + + + + + @@ -409,7 +438,7 @@ - + @@ -470,6 +499,30 @@ + + + + attention + author + authors + bug + copyright + date + invariant + note + post + pre + remark + remarks + sa + see + since + todo + version + warning + + + diff --git a/docs/AddressSanitizer.html b/docs/AddressSanitizer.html deleted file mode 100644 index 397eafc2d51b..000000000000 --- a/docs/AddressSanitizer.html +++ /dev/null @@ -1,171 +0,0 @@ - - - - - - AddressSanitizer, a fast memory error detector - - - - - - - - -
- -

AddressSanitizer

- - -

Introduction

-AddressSanitizer is a fast memory error detector. -It consists of a compiler instrumentation module and a run-time library. -The tool can detect the following types of bugs: -
  • Out-of-bounds accesses to heap, stack and globals -
  • Use-after-free -
  • Use-after-return (to some extent) -
  • Double-free, invalid free -
-Typical slowdown introduced by AddressSanitizer is 2x. - -

How to build

-Follow the clang build instructions. -CMake build is supported.
- -

Usage

-Simply compile and link your program with -fsanitize=address flag.
-The AddressSanitizer run-time library should be linked to the final executable, -so make sure to use clang (not ld) for the final link step.
-When linking shared libraries, the AddressSanitizer run-time is not linked, -so -Wl,-z,defs may cause link errors (don't use it with AddressSanitizer).
- -To get a reasonable performance add -O1 or higher.
-To get nicer stack traces in error messages add --fno-omit-frame-pointer.
-To get perfect stack traces you may need to disable inlining (just use -O1) and tail call -elimination (-fno-optimize-sibling-calls). - -
-% cat example_UseAfterFree.cc
-int main(int argc, char **argv) {
-  int *array = new int[100];
-  delete [] array;
-  return array[argc];  // BOOM
-}
-
- -
-# Compile and link
-% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc
-
-OR -
-# Compile
-% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc
-# Link
-% clang -g -fsanitize=address example_UseAfterFree.o
-
- -If a bug is detected, the program will print an error message to stderr and exit with a -non-zero exit code. -Currently, AddressSanitizer does not symbolize its output, so you may need to use a -separate script to symbolize the result offline (this will be fixed in future). -
-% ./a.out 2> log
-% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
-==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
-READ of size 4 at 0x7f7ddab8c084 thread T0
-    #0 0x403c8c in main example_UseAfterFree.cc:4
-    #1 0x7f7ddabcac4d in __libc_start_main ??:0
-0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
-freed by thread T0 here:
-    #0 0x404704 in operator delete[](void*) ??:0
-    #1 0x403c53 in main example_UseAfterFree.cc:4
-    #2 0x7f7ddabcac4d in __libc_start_main ??:0
-previously allocated by thread T0 here:
-    #0 0x404544 in operator new[](unsigned long) ??:0
-    #1 0x403c43 in main example_UseAfterFree.cc:2
-    #2 0x7f7ddabcac4d in __libc_start_main ??:0
-==9442== ABORTING
-
- -AddressSanitizer exits on the first detected error. This is by design. -One reason: it makes the generated code smaller and faster (both by ~5%). -Another reason: this makes fixing bugs unavoidable. With Valgrind, it is often -the case that users treat Valgrind warnings as false positives -(which they are not) and don't fix them. - - -

__has_feature(address_sanitizer)

-In some cases one may need to execute different code depending on whether -AddressSanitizer is enabled. -__has_feature -can be used for this purpose. -
-#if defined(__has_feature)
-# if __has_feature(address_sanitizer)
-  code that builds only under AddressSanitizer
-# endif
-#endif
-
- -

__attribute__((no_address_safety_analysis))

-Some code should not be instrumented by AddressSanitizer. -One may use the function attribute - - no_address_safety_analysis -to disable instrumentation of a particular function. -This attribute may not be supported by other compilers, so we suggest to -use it together with __has_feature(address_sanitizer). -Note: currently, this attribute will be lost if the function is inlined. - -

Supported Platforms

-AddressSanitizer is supported on -
  • Linux i386/x86_64 (tested on Ubuntu 10.04 and 12.04). -
  • MacOS 10.6, 10.7 and 10.8 (i386/x86_64). -
-Support for Linux ARM (and Android ARM) is in progress -(it may work, but is not guaranteed too). - - -

Limitations

-
    -
  • AddressSanitizer uses more real memory than a native run. -Exact overhead depends on the allocations sizes. The smaller the -allocations you make the bigger the overhead is. -
  • AddressSanitizer uses more stack memory. We have seen up to 3x increase. -
  • On 64-bit platforms AddressSanitizer maps (but not reserves) -16+ Terabytes of virtual address space. -This means that tools like ulimit may not work as usually expected. -
  • Static linking is not supported. -
- - -

Current Status

-AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1. -The test suite is integrated into CMake build and can be run with -make check-asan command. - -

More Information

-http://code.google.com/p/address-sanitizer. - - -
- - diff --git a/docs/AddressSanitizer.rst b/docs/AddressSanitizer.rst new file mode 100644 index 000000000000..89e864450009 --- /dev/null +++ b/docs/AddressSanitizer.rst @@ -0,0 +1,163 @@ +================ +AddressSanitizer +================ + +.. contents:: + :local: + +Introduction +============ + +AddressSanitizer is a fast memory error detector. It consists of a compiler +instrumentation module and a run-time library. The tool can detect the +following types of bugs: + +* Out-of-bounds accesses to heap, stack and globals +* Use-after-free +* Use-after-return (to some extent) +* Double-free, invalid free + +Typical slowdown introduced by AddressSanitizer is **2x**. + +How to build +============ + +Follow the `clang build instructions <../get_started.html>`_. CMake build is +supported. + +Usage +===== + +Simply compile and link your program with ``-fsanitize=address`` flag. The +AddressSanitizer run-time library should be linked to the final executable, so +make sure to use ``clang`` (not ``ld``) for the final link step. When linking +shared libraries, the AddressSanitizer run-time is not linked, so +``-Wl,-z,defs`` may cause link errors (don't use it with AddressSanitizer). To +get a reasonable performance add ``-O1`` or higher. To get nicer stack traces +in error messages add ``-fno-omit-frame-pointer``. To get perfect stack traces +you may need to disable inlining (just use ``-O1``) and tail call elimination +(``-fno-optimize-sibling-calls``). + +.. code-block:: console + + % cat example_UseAfterFree.cc + int main(int argc, char **argv) { + int *array = new int[100]; + delete [] array; + return array[argc]; // BOOM + } + + # Compile and link + % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc + +or: + +.. code-block:: console + + # Compile + % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc + # Link + % clang -g -fsanitize=address example_UseAfterFree.o + +If a bug is detected, the program will print an error message to stderr and +exit with a non-zero exit code. Currently, AddressSanitizer does not symbolize +its output, so you may need to use a separate script to symbolize the result +offline (this will be fixed in future). + +.. code-block:: console + + % ./a.out 2> log + % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt + ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8 + READ of size 4 at 0x7f7ddab8c084 thread T0 + #0 0x403c8c in main example_UseAfterFree.cc:4 + #1 0x7f7ddabcac4d in __libc_start_main ??:0 + 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210) + freed by thread T0 here: + #0 0x404704 in operator delete[](void*) ??:0 + #1 0x403c53 in main example_UseAfterFree.cc:4 + #2 0x7f7ddabcac4d in __libc_start_main ??:0 + previously allocated by thread T0 here: + #0 0x404544 in operator new[](unsigned long) ??:0 + #1 0x403c43 in main example_UseAfterFree.cc:2 + #2 0x7f7ddabcac4d in __libc_start_main ??:0 + ==9442== ABORTING + +AddressSanitizer exits on the first detected error. This is by design. +One reason: it makes the generated code smaller and faster (both by +~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind, +it is often the case that users treat Valgrind warnings as false +positives (which they are not) and don't fix them. + +``__has_feature(address_sanitizer)`` +------------------------------------ + +In some cases one may need to execute different code depending on whether +AddressSanitizer is enabled. +:ref:`\_\_has\_feature ` can be used for +this purpose. + +.. code-block:: c + + #if defined(__has_feature) + # if __has_feature(address_sanitizer) + // code that builds only under AddressSanitizer + # endif + #endif + +``__attribute__((no_sanitize_address))`` +----------------------------------------------- + +Some code should not be instrumented by AddressSanitizer. One may use the +function attribute +:ref:`no_sanitize_address ` +(or a deprecated synonym `no_address_safety_analysis`) +to disable instrumentation of a particular function. This attribute may not be +supported by other compilers, so we suggest to use it together with +``__has_feature(address_sanitizer)``. Note: currently, this attribute will be +lost if the function is inlined. + +Initialization order checking +----------------------------- + +AddressSanitizer can optionally detect dynamic initialization order problems, +when initialization of globals defined in one translation unit uses +globals defined in another translation unit. To enable this check at runtime, +you should set environment variable +``ASAN_OPTIONS=check_initialization_order=1``. + +Supported Platforms +=================== + +AddressSanitizer is supported on + +* Linux i386/x86\_64 (tested on Ubuntu 10.04 and 12.04); +* MacOS 10.6, 10.7 and 10.8 (i386/x86\_64). + +Support for Linux ARM (and Android ARM) is in progress (it may work, but +is not guaranteed too). + +Limitations +=========== + +* AddressSanitizer uses more real memory than a native run. Exact overhead + depends on the allocations sizes. The smaller the allocations you make the + bigger the overhead is. +* AddressSanitizer uses more stack memory. We have seen up to 3x increase. +* On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of + virtual address space. This means that tools like ``ulimit`` may not work as + usually expected. +* Static linking is not supported. + +Current Status +============== + +AddressSanitizer is fully functional on supported platforms starting from LLVM +3.1. The test suite is integrated into CMake build and can be run with ``make +check-asan`` command. + +More Information +================ + +`http://code.google.com/p/address-sanitizer `_ + diff --git a/docs/AnalyzerRegions.html b/docs/AnalyzerRegions.html deleted file mode 100644 index f9d333792045..000000000000 --- a/docs/AnalyzerRegions.html +++ /dev/null @@ -1,260 +0,0 @@ - - - -Static Analyzer Design Document: Memory Regions - - - -

Static Analyzer Design Document: Memory Regions

- -

Authors

- -

Ted Kremenek, kremenek at apple
-Zhongxing Xu, xuzhongzhing at gmail

- -

Introduction

- -

The path-sensitive analysis engine in libAnalysis employs an extensible API -for abstractly modeling the memory of an analyzed program. This API employs the -concept of "memory regions" to abstractly model chunks of program memory such as -program variables and dynamically allocated memory such as those returned from -'malloc' and 'alloca'. Regions are hierarchical, with subregions modeling -subtyping relationships, field and array offsets into larger chunks of memory, -and so on.

- -

The region API consists of two components:

- -
  • A taxonomy and representation of regions themselves within the analyzer -engine. The primary definitions and interfaces are described in MemRegion.h. -At the root of the region hierarchy is the class MemRegion with -specific subclasses refining the region concept for variables, heap allocated -memory, and so forth.
  • The modeling of binding of values to regions. For -example, modeling the value stored to a local variable x consists of -recording the binding between the region for x (which represents the -raw memory associated with x) and the value stored to x. This -binding relationship is captured with the notion of "symbolic -stores."
- -

Symbolic stores, which can be thought of as representing the relation -regions -> values, are implemented by subclasses of the -StoreManager class (Store.h). A -particular StoreManager implementation has complete flexibility concerning the -following: - -

    -
  • How to model the binding between regions and values
    • -
  • What bindings are recorded -
- -

Together, both points allow different StoreManagers to tradeoff between -different levels of analysis precision and scalability concerning the reasoning -of program memory. Meanwhile, the core path-sensitive engine makes no -assumptions about either points, and queries a StoreManager about the bindings -to a memory region through a generic interface that all StoreManagers share. If -a particular StoreManager cannot reason about the potential bindings of a given -memory region (e.g., 'BasicStoreManager' does not reason about fields -of structures) then the StoreManager can simply return 'unknown' (represented by -'UnknownVal') for a particular region-binding. This separation of -concerns not only isolates the core analysis engine from the details of -reasoning about program memory but also facilities the option of a client of the -path-sensitive engine to easily swap in different StoreManager implementations -that internally reason about program memory in very different ways.

- -

The rest of this document is divided into two parts. We first discuss region -taxonomy and the semantics of regions. We then discuss the StoreManager -interface, and details of how the currently available StoreManager classes -implement region bindings.

- -

Memory Regions and Region Taxonomy

- -

Pointers

- -

Before talking about the memory regions, we would talk about the pointers -since memory regions are essentially used to represent pointer values.

- -

The pointer is a type of values. Pointer values have two semantic aspects. -One is its physical value, which is an address or location. The other is the -type of the memory object residing in the address.

- -

Memory regions are designed to abstract these two properties of the pointer. -The physical value of a pointer is represented by MemRegion pointers. The rvalue -type of the region corresponds to the type of the pointee object.

- -

One complication is that we could have different view regions on the same -memory chunk. They represent the same memory location, but have different -abstract location, i.e., MemRegion pointers. Thus we need to canonicalize the -abstract locations to get a unique abstract location for one physical -location.

- -

Furthermore, these different view regions may or may not represent memory -objects of different types. Some different types are semantically the same, -for example, 'struct s' and 'my_type' are the same type.

- -
-struct s;
-typedef struct s my_type;
-
- -

But char and int are not the same type in the code below:

- -
-void *p;
-int *q = (int*) p;
-char *r = (char*) p;
-
- -

Thus we need to canonicalize the MemRegion which is used in binding and -retrieving.

- -

Regions

-

Region is the entity used to model pointer values. A Region has the following -properties:

- -
    -
  • Kind
    • - -
  • ObjectType: the type of the object residing on the region.
    • - -
  • LocationType: the type of the pointer value that the region corresponds to. - Usually this is the pointer to the ObjectType. But sometimes we want to cache - this type explicitly, for example, for a CodeTextRegion.
    • - -
  • StartLocation
    • - -
  • EndLocation
    • -
- -

Symbolic Regions

- -

A symbolic region is a map of the concept of symbolic values into the domain -of regions. It is the way that we represent symbolic pointers. Whenever a -symbolic pointer value is needed, a symbolic region is created to represent -it.

- -

A symbolic region has no type. It wraps a SymbolData. But sometimes we have -type information associated with a symbolic region. For this case, a -TypedViewRegion is created to layer the type information on top of the symbolic -region. The reason we do not carry type information with the symbolic region is -that the symbolic regions can have no type. To be consistent, we don't let them -to carry type information.

- -

Like a symbolic pointer, a symbolic region may be NULL, has unknown extent, -and represents a generic chunk of memory.

- -

NOTE: We plan not to use loc::SymbolVal in RegionStore and remove it - gradually.

- -

Symbolic regions get their rvalue types through the following ways:

- -
    -
  • Through the parameter or global variable that points to it, e.g.: -
    -void f(struct s* p) {
-  ...
-}
-
    - -

    The symbolic region pointed to by p has type struct -s.

    • - -
  • Through explicit or implicit casts, e.g.: -
    -void f(void* p) {
-  struct s* q = (struct s*) p;
-  ...
-}
-
    -
    • -
- -

We attach the type information to the symbolic region lazily. For the first -case above, we create the TypedViewRegion only when the pointer is -actually used to access the pointee memory object, that is when the element or -field region is created. For the cast case, the TypedViewRegion is -created when visiting the CastExpr.

- -

The reason for doing lazy typing is that symbolic regions are sometimes only -used to do location comparison.

- -

Pointer Casts

- -

Pointer casts allow people to impose different 'views' onto a chunk of -memory.

- -

Usually we have two kinds of casts. One kind of casts cast down with in the -type hierarchy. It imposes more specific views onto more generic memory regions. -The other kind of casts cast up with in the type hierarchy. It strips away more -specific views on top of the more generic memory regions.

- -

We simulate the down casts by layering another TypedViewRegion on -top of the original region. We simulate the up casts by striping away the top -TypedViewRegion. Down casts is usually simple. For up casts, if the -there is no TypedViewRegion to be stripped, we return the original -region. If the underlying region is of the different type than the cast-to type, -we flag an error state.

- -

For toll-free bridging casts, we return the original region.

- -

We can set up a partial order for pointer types, with the most general type -void* at the top. The partial order forms a tree with void* as -its root node.

- -

Every MemRegion has a root position in the type tree. For example, -the pointee region of void *p has its root position at the root node of -the tree. VarRegion of int x has its root position at the 'int -type' node.

- -

TypedViewRegion is used to move the region down or up in the tree. -Moving down in the tree adds a TypedViewRegion. Moving up in the tree -removes a TypedViewRegion.

- -

Do we want to allow moving up beyond the root position? This happens -when:

 int x; void *p = &x;
- -

The region of x has its root position at 'int*' node. the cast to -void* moves that region up to the 'void*' node. I propose to not allow such -casts, and assign the region of x for p.

- -

Another non-ideal case is that people might cast to a non-generic pointer -from another non-generic pointer instead of first casting it back to the generic -pointer. Direct handling of this case would result in multiple layers of -TypedViewRegions. This enforces an incorrect semantic view to the region, -because we can only have one typed view on a region at a time. To avoid this -inconsistency, before casting the region, we strip the TypedViewRegion, then do -the cast. In summary, we only allow one layer of TypedViewRegion.

- -

Region Bindings

- -

The following region kinds are boundable: VarRegion, CompoundLiteralRegion, -StringRegion, ElementRegion, FieldRegion, and ObjCIvarRegion.

- -

When binding regions, we perform canonicalization on element regions and field -regions. This is because we can have different views on the same region, some -of which are essentially the same view with different sugar type names.

- -

To canonicalize a region, we get the canonical types for all TypedViewRegions -along the way up to the root region, and make new TypedViewRegions with those -canonical types.

- -

For Objective-C and C++, perhaps another canonicalization rule should be -added: for FieldRegion, the least derived class that has the field is used as -the type of the super region of the FieldRegion.

- -

All bindings and retrievings are done on the canonicalized regions.

- -

Canonicalization is transparent outside the region store manager, and more -specifically, unaware outside the Bind() and Retrieve() method. We don't need to -consider region canonicalization when doing pointer cast.

- -

Constraint Manager

- -

The constraint manager reasons about the abstract location of memory objects. -We can have different views on a region, but none of these views changes the -location of that object. Thus we should get the same abstract location for those -regions.

- - - diff --git a/docs/AutomaticReferenceCounting.html b/docs/AutomaticReferenceCounting.html deleted file mode 100644 index 5354f8af3466..000000000000 --- a/docs/AutomaticReferenceCounting.html +++ /dev/null @@ -1,2226 +0,0 @@ - - - -Objective-C Automatic Reference Counting (ARC) - - - - - - - - - - -
-

Automatic Reference Counting

- -
-
- -
-

About this document

- -
-

Purpose

- -

The first and primary purpose of this document is to serve as a -complete technical specification of Automatic Reference Counting. -Given a core Objective-C compiler and runtime, it should be possible -to write a compiler and runtime which implements these new -semantics.

- -

The secondary purpose is to act as a rationale for why ARC was -designed in this way. This should remain tightly focused on the -technical design and should not stray into marketing speculation.

- -
- -
-

Background

- -

This document assumes a basic familiarity with C.

- -

Blocks are a C language extension for -creating anonymous functions. Users interact with and transfer block -objects using block pointers, which are -represented like a normal pointer. A block may capture values from -local variables; when this occurs, memory must be dynamically -allocated. The initial allocation is done on the stack, but the -runtime provides a Block_copy function which, given a block -pointer, either copies the underlying block object to the heap, -setting its reference count to 1 and returning the new block pointer, -or (if the block object is already on the heap) increases its -reference count by 1. The paired function is Block_release, -which decreases the reference count by 1 and destroys the object if -the count reaches zero and is on the heap.

- -

Objective-C is a set of language extensions, significant enough to -be considered a different language. It is a strict superset of C. -The extensions can also be imposed on C++, producing a language called -Objective-C++. The primary feature is a single-inheritance object -system; we briefly describe the modern dialect.

- -

Objective-C defines a new type kind, collectively called -the object pointer types. This kind has two -notable builtin members, id and Class; id -is the final supertype of all object pointers. The validity of -conversions between object pointer types is not checked at runtime. -Users may define classes; each class is a -type, and the pointer to that type is an object pointer type. A class -may have a superclass; its pointer type is a subtype of its -superclass's pointer type. A class has a set -of ivars, fields which appear on all -instances of that class. For every class T there's an -associated metaclass; it has no fields, its superclass is the -metaclass of T's superclass, and its metaclass is a global -class. Every class has a global object whose class is the -class's metaclass; metaclasses have no associated type, so pointers to -this object have type Class.

- -

A class declaration (@interface) declares a set -of methods. A method has a return type, a -list of argument types, and a selector: a -name like foo:bar:baz:, where the number of colons -corresponds to the number of formal arguments. A method may be an -instance method, in which case it can be invoked on objects of the -class, or a class method, in which case it can be invoked on objects -of the metaclass. A method may be invoked by providing an object -(called the receiver) and a list of formal -arguments interspersed with the selector, like so:

- -
[receiver foo: fooArg bar: barArg baz: bazArg]
- -

This looks in the dynamic class of the receiver for a method with -this name, then in that class's superclass, etc., until it finds -something it can execute. The receiver expression may also be -the name of a class, in which case the actual receiver is the class -object for that class, or (within method definitions) it may -be super, in which case the lookup algorithm starts with the -static superclass instead of the dynamic class. The actual methods -dynamically found in a class are not those declared in the -@interface, but those defined in a separate -@implementation declaration; however, when compiling a -call, typechecking is done based on the methods declared in the -@interface.

- -

Method declarations may also be grouped into -protocols, which are not inherently -associated with any class, but which classes may claim to follow. -Object pointer types may be qualified with additional protocols that -the object is known to support.

- -

Class extensions are collections of ivars -and methods, designed to allow a class's @interface to be -split across multiple files; however, there is still a primary -implementation file which must see the @interfaces of all -class extensions. -Categories allow methods (but not ivars) to -be declared post hoc on an arbitrary class; the methods in the -category's @implementation will be dynamically added to that -class's method tables which the category is loaded at runtime, -replacing those methods in case of a collision.

- -

In the standard environment, objects are allocated on the heap, and -their lifetime is manually managed using a reference count. This is -done using two instance methods which all classes are expected to -implement: retain increases the object's reference count by -1, whereas release decreases it by 1 and calls the instance -method dealloc if the count reaches 0. To simplify certain -operations, there is also an autorelease -pool, a thread-local list of objects to call release -on later; an object can be added to this pool by -calling autorelease on it.

- -

Block pointers may be converted to type id; block objects -are laid out in a way that makes them compatible with Objective-C -objects. There is a builtin class that all block objects are -considered to be objects of; this class implements retain by -adjusting the reference count, not by calling Block_copy.

- -
- -
-

Evolution

- -

ARC is under continual evolution, and this document must be updated -as the language progresses.

- -

If a change increases the expressiveness of the language, for -example by lifting a restriction or by adding new syntax, the change -will be annotated with a revision marker, like so:

- -
- ARC applies to Objective-C pointer types, block pointer types, and - [beginning Apple - 8.0, LLVM 3.8] BPTRs declared within extern - "BCPL" blocks. -
- -

For now, it is sensible to version this document by the releases of -its sole implementation (and its host project), clang. -LLVM X.Y refers to an open-source release of clang from the -LLVM project. Apple X.Y refers to an Apple-provided release of -the Apple LLVM Compiler. Other organizations that prepare their own, -separately-versioned clang releases and wish to maintain similar -information in this document should send requests to cfe-dev.

- -

If a change decreases the expressiveness of the language, for -example by imposing a new restriction, this should be taken as an -oversight in the original specification and something to be avoided -in all versions. Such changes are generally to be avoided.

- -
- -
- -
-

General

- -

Automatic Reference Counting implements automatic memory management -for Objective-C objects and blocks, freeing the programmer from the -need to explicitly insert retains and releases. It does not provide a -cycle collector; users must explicitly manage the lifetime of their -objects, breaking cycles manually or with weak or unsafe -references.

- -

ARC may be explicitly enabled with the compiler -flag -fobjc-arc. It may also be explicitly disabled with the -compiler flag -fno-objc-arc. The last of these two flags -appearing on the compile line wins.

- -

If ARC is enabled, __has_feature(objc_arc) will expand to -1 in the preprocessor. For more information about __has_feature, -see the language -extensions document.

- -
- -
-

Retainable object pointers

- -

This section describes retainable object pointers, their basic -operations, and the restrictions imposed on their use under ARC. Note -in particular that it covers the rules for pointer values -(patterns of bits indicating the location of a pointed-to object), not -pointer -objects (locations in memory which store pointer values). -The rules for objects are covered in the next section.

- -

A retainable object pointer -(or retainable pointer) is a value of -a retainable object pointer type -(retainable type). There are three kinds of retainable object -pointer types:

-
    -
  • block pointers (formed by applying the caret (^) -declarator sigil to a function type)
    • -
  • Objective-C object pointers (id, Class, NSFoo*, etc.)
    • -
  • typedefs marked with __attribute__((NSObject))
    • -
- -

Other pointer types, such as int* and CFStringRef, -are not subject to ARC's semantics and restrictions.

- -
- -

Rationale: We are not at liberty to require -all code to be recompiled with ARC; therefore, ARC must interoperate -with Objective-C code which manages retains and releases manually. In -general, there are three requirements in order for a -compiler-supported reference-count system to provide reliable -interoperation:

- -
    -
  • The type system must reliably identify which objects are to be -managed. An int* might be a pointer to a malloc'ed -array, or it might be an interior pointer to such an array, or it might -point to some field or local variable. In contrast, values of the -retainable object pointer types are never interior.
    • -
  • The type system must reliably indicate how to -manage objects of a type. This usually means that the type must imply -a procedure for incrementing and decrementing retain counts. -Supporting single-ownership objects requires a lot more explicit -mediation in the language.
    • -
  • There must be reliable conventions for whether and -when ownership is passed between caller and callee, for both -arguments and return values. Objective-C methods follow such a -convention very reliably, at least for system libraries on Mac OS X, -and functions always pass objects at +0. The C-based APIs for Core -Foundation objects, on the other hand, have much more varied transfer -semantics.
    • -
-
- -

The use of __attribute__((NSObject)) typedefs is not -recommended. If it's absolutely necessary to use this attribute, be -very explicit about using the typedef, and do not assume that it will -be preserved by language features like __typeof and C++ -template argument substitution.

- -

Rationale: any compiler operation which -incidentally strips type sugar from a type will yield a type -without the attribute, which may result in unexpected -behavior.

- -
-

Retain count semantics

- -

A retainable object pointer is either a null -pointer or a pointer to a valid object. Furthermore, if it has -block pointer type and is not null then it must actually be a -pointer to a block object, and if it has Class type (possibly -protocol-qualified) then it must actually be a pointer to a class -object. Otherwise ARC does not enforce the Objective-C type system as -long as the implementing methods follow the signature of the static -type. It is undefined behavior if ARC is exposed to an invalid -pointer.

- -

For ARC's purposes, a valid object is one with well-behaved -retaining operations. Specifically, the object must be laid out such -that the Objective-C message send machinery can successfully send it -the following messages:

- -
    -
  • retain, taking no arguments and returning a pointer to -the object.
    • -
  • release, taking no arguments and returning void.
    • -
  • autorelease, taking no arguments and returning a pointer -to the object.
    • -
- -

The behavior of these methods is constrained in the following ways. -The term high-level semantics is an -intentionally vague term; the intent is that programmers must -implement these methods in a way such that the compiler, modifying -code in ways it deems safe according to these constraints, will not -violate their requirements. For example, if the user puts logging -statements in retain, they should not be surprised if those -statements are executed more or less often depending on optimization -settings. These constraints are not exhaustive of the optimization -opportunities: values held in local variables are subject to -additional restrictions, described later in this document.

- -

It is undefined behavior if a computation history featuring a send -of retain followed by a send of release to the same -object, with no intervening release on that object, is not -equivalent under the high-level semantics to a computation -history in which these sends are removed. Note that this implies that -these methods may not raise exceptions.

- -

It is undefined behavior if a computation history features any use -whatsoever of an object following the completion of a send -of release that is not preceded by a send of retain -to the same object.

- -

The behavior of autorelease must be equivalent to sending -release when one of the autorelease pools currently in scope -is popped. It may not throw an exception.

- -

When the semantics call for performing one of these operations on a -retainable object pointer, if that pointer is null then the -effect is a no-op.

- -

All of the semantics described in this document are subject to -additional optimization rules which permit -the removal or optimization of operations based on local knowledge of -data flow. The semantics describe the high-level behaviors that the -compiler implements, not an exact sequence of operations that a -program will be compiled into.

- -
- -
-

Retainable object pointers as operands and arguments

- -

In general, ARC does not perform retain or release operations when -simply using a retainable object pointer as an operand within an -expression. This includes:

-
    -
  • loading a retainable pointer from an object with non-weak -ownership,
    • -
  • passing a retainable pointer as an argument to a function or -method, and
    • -
  • receiving a retainable pointer as the result of a function or -method call.
    • -
- -

Rationale: while this might seem -uncontroversial, it is actually unsafe when multiple expressions are -evaluated in parallel, as with binary operators and calls, -because (for example) one expression might load from an object while -another writes to it. However, C and C++ already call this undefined -behavior because the evaluations are unsequenced, and ARC simply -exploits that here to avoid needing to retain arguments across a large -number of calls.

- -

The remainder of this section describes exceptions to these rules, -how those exceptions are detected, and what those exceptions imply -semantically.

- -
-

Consumed parameters

- -

A function or method parameter of retainable object pointer type -may be marked as consumed, signifying that -the callee expects to take ownership of a +1 retain count. This is -done by adding the ns_consumed attribute to the parameter -declaration, like so:

- -
void foo(__attribute((ns_consumed)) id x);
-- (void) foo: (id) __attribute((ns_consumed)) x;
- -

This attribute is part of the type of the function or method, not -the type of the parameter. It controls only how the argument is -passed and received.

- -

When passing such an argument, ARC retains the argument prior to -making the call.

- -

When receiving such an argument, ARC releases the argument at the -end of the function, subject to the usual optimizations for local -values.

- -

Rationale: this formalizes direct transfers -of ownership from a caller to a callee. The most common scenario here -is passing the self parameter to init, but it is -useful to generalize. Typically, local optimization will remove any -extra retains and releases: on the caller side the retain will be -merged with a +1 source, and on the callee side the release will be -rolled into the initialization of the parameter.

- -

The implicit self parameter of a method may be marked as -consumed by adding __attribute__((ns_consumes_self)) to the -method declaration. Methods in the init -family are treated as if they were implicitly -marked with this attribute.

- -

It is undefined behavior if an Objective-C message send to a method -with ns_consumed parameters (other than self) is made with a -null receiver. It is undefined behavior if the method to which an -Objective-C message send statically resolves to has a different set -of ns_consumed parameters than the method it dynamically -resolves to. It is undefined behavior if a block or function call is -made through a static type with a different set of ns_consumed -parameters than the implementation of the called block or function.

- -

Rationale: consumed parameters with null -receiver are a guaranteed leak. Mismatches with consumed parameters -will cause over-retains or over-releases, depending on the direction. -The rule about function calls is really just an application of the -existing C/C++ rule about calling functions through an incompatible -function type, but it's useful to state it explicitly.

- -
- -
-

Retained return values

- -

A function or method which returns a retainable object pointer type -may be marked as returning a retained value, signifying that the -caller expects to take ownership of a +1 retain count. This is done -by adding the ns_returns_retained attribute to the function or -method declaration, like so:

- -
id foo(void) __attribute((ns_returns_retained));
-- (id) foo __attribute((ns_returns_retained));
- -

This attribute is part of the type of the function or method.

- -

When returning from such a function or method, ARC retains the -value at the point of evaluation of the return statement, before -leaving all local scopes.

- -

When receiving a return result from such a function or method, ARC -releases the value at the end of the full-expression it is contained -within, subject to the usual optimizations for local values.

- -

Rationale: this formalizes direct transfers of -ownership from a callee to a caller. The most common scenario this -models is the retained return from init, alloc, -new, and copy methods, but there are other cases in -the frameworks. After optimization there are typically no extra -retains and releases required.

- -

Methods in -the alloc, copy, init, mutableCopy, -and new families are implicitly marked -__attribute__((ns_returns_retained)). This may be suppressed -by explicitly marking the -method __attribute__((ns_returns_not_retained)).

- -

It is undefined behavior if the method to which an Objective-C -message send statically resolves has different retain semantics on its -result from the method it dynamically resolves to. It is undefined -behavior if a block or function call is made through a static type -with different retain semantics on its result from the implementation -of the called block or function.

- -

Rationale: Mismatches with returned results -will cause over-retains or over-releases, depending on the direction. -Again, the rule about function calls is really just an application of -the existing C/C++ rule about calling functions through an -incompatible function type.

- -
- -
-

Unretained return values

- -

A method or function which returns a retainable object type but -does not return a retained value must ensure that the object is -still valid across the return boundary.

- -

When returning from such a function or method, ARC retains the -value at the point of evaluation of the return statement, then leaves -all local scopes, and then balances out the retain while ensuring that -the value lives across the call boundary. In the worst case, this may -involve an autorelease, but callers must not assume that the -value is actually in the autorelease pool.

- -

ARC performs no extra mandatory work on the caller side, although -it may elect to do something to shorten the lifetime of the returned -value.

- -

Rationale: it is common in non-ARC code to not -return an autoreleased value; therefore the convention does not force -either path. It is convenient to not be required to do unnecessary -retains and autoreleases; this permits optimizations such as eliding -retain/autoreleases when it can be shown that the original pointer -will still be valid at the point of return.

- -

A method or function may be marked -with __attribute__((ns_returns_autoreleased)) to indicate -that it returns a pointer which is guaranteed to be valid at least as -long as the innermost autorelease pool. There are no additional -semantics enforced in the definition of such a method; it merely -enables optimizations in callers.

- -
- -
-

Bridged casts

- -

A bridged cast is a C-style cast -annotated with one of three keywords:

- -
    -
  • (__bridge T) op casts the operand to the destination -type T. If T is a retainable object pointer type, -then op must have a non-retainable pointer type. -If T is a non-retainable pointer type, then op must -have a retainable object pointer type. Otherwise the cast is -ill-formed. There is no transfer of ownership, and ARC inserts -no retain operations.
    • - -
  • (__bridge_retained T) op casts the operand, which must -have retainable object pointer type, to the destination type, which -must be a non-retainable pointer type. ARC retains the value, subject -to the usual optimizations on local values, and the recipient is -responsible for balancing that +1.
    • - -
  • (__bridge_transfer T) op casts the operand, which must -have non-retainable pointer type, to the destination type, which must -be a retainable object pointer type. ARC will release the value at -the end of the enclosing full-expression, subject to the usual -optimizations on local values.
    • -
- -

These casts are required in order to transfer objects in and out of -ARC control; see the rationale in the section -on conversion of retainable -object pointers.

- -

Using a __bridge_retained or __bridge_transfer -cast purely to convince ARC to emit an unbalanced retain or release, -respectively, is poor form.

- -
- -
- -
-

Restrictions

- -
-

Conversion of retainable object pointers

- -

In general, a program which attempts to implicitly or explicitly -convert a value of retainable object pointer type to any -non-retainable type, or vice-versa, is ill-formed. For example, an -Objective-C object pointer shall not be converted to void*. -As an exception, cast to intptr_t is allowed because such -casts are not transferring ownership. The bridged -casts may be used to perform these conversions where -necessary.

- -

Rationale: we cannot ensure the correct -management of the lifetime of objects if they may be freely passed -around as unmanaged types. The bridged casts are provided so that the -programmer may explicitly describe whether the cast transfers control -into or out of ARC.

- -

However, the following exceptions apply.

- -
- -
-

Conversion to retainable object pointer type of - expressions with known semantics

- -

[beginning Apple - 4.0, LLVM 3.1] These exceptions have been greatly expanded; - they previously applied only to a much-reduced subset which is - difficult to categorize but which included null pointers, message - sends (under the given rules), and the various global constants.

- -

An unbridged conversion to a retainable object pointer type from a -type other than a retainable object pointer type is ill-formed, as -discussed above, unless the operand of the cast has a syntactic form -which is known retained, known unretained, or known -retain-agnostic.

- -

An expression is known retain-agnostic if -it is:

-
    -
  • an Objective-C string literal,
    • -
  • a load from a const system global variable of -C retainable pointer type, or
    • -
  • a null pointer constant.
    • -
- -

An expression is known unretained if it -is an rvalue of C retainable -pointer type and it is:

-
    -
  • a direct call to a function, and either that function has the - cf_returns_not_retained attribute or it is an - audited function that does not - have the cf_returns_retained attribute and does not follow - the create/copy naming convention,
    • -
  • a message send, and the declared method either has - the cf_returns_not_retained attribute or it has neither - the cf_returns_retained attribute nor a - selector family that implies a retained - result.
    • -
- -

An expression is known retained if it is -an rvalue of C retainable pointer type -and it is:

-
    -
  • a message send, and the declared method either has the - cf_returns_retained attribute, or it does not have - the cf_returns_not_retained attribute but it does have a - selector family that implies a retained - result.
    • -
- -

Furthermore:

-
    -
  • a comma expression is classified according to its right-hand side,
    • -
  • a statement expression is classified according to its result -expression, if it has one,
    • -
  • an lvalue-to-rvalue conversion applied to an Objective-C property -lvalue is classified according to the underlying message send, and
    • -
  • a conditional operator is classified according to its second and -third operands, if they agree in classification, or else the other -if one is known retain-agnostic.
    • -
- -

If the cast operand is known retained, the conversion is treated as -a __bridge_transfer cast. If the cast operand is known -unretained or known retain-agnostic, the conversion is treated as -a __bridge cast.

- -

Rationale: Bridging casts are annoying. -Absent the ability to completely automate the management of CF -objects, however, we are left with relatively poor attempts to reduce -the need for a glut of explicit bridges. Hence these rules.

- -

We've so far consciously refrained from implicitly turning retained -CF results from function calls into __bridge_transfer casts. -The worry is that some code patterns — for example, creating a -CF value, assigning it to an ObjC-typed local, and then -calling CFRelease when done — are a bit too likely to -be accidentally accepted, leading to mysterious behavior.

- -
- -
-

Conversion from retainable object pointer type in certain contexts

- -

[beginning Apple - 4.0, LLVM 3.1]

- -

If an expression of retainable object pointer type is explicitly -cast to a C retainable pointer type, -the program is ill-formed as discussed above unless the result is -immediately used:

- -
    -
  • to initialize a parameter in an Objective-C message send where the -parameter is not marked with the cf_consumed attribute, or
    • -
  • to initialize a parameter in a direct call to -an audited function where the -parameter is not marked with the cf_consumed attribute.
    • -
- -

Rationale: Consumed parameters are left out -because ARC would naturally balance them with a retain, which was -judged too treacherous. This is in part because several of the most -common consuming functions are in the Release family, and it -would be quite unfortunate for explicit releases to be silently -balanced out in this way.

- -
- -
- -
- -
-

Ownership qualification

- -

This section describes the behavior of objects of -retainable object pointer type; that is, locations in memory which -store retainable object pointers.

- -

A type is a retainable object owner type -if it is a retainable object pointer type or an array type whose -element type is a retainable object owner type.

- -

An ownership qualifier is a type -qualifier which applies only to retainable object owner types. An array type is -ownership-qualified according to its element type, and adding an ownership -qualifier to an array type so qualifies its element type.

- -

A program is ill-formed if it attempts to apply an ownership qualifier -to a type which is already ownership-qualified, even if it is the same -qualifier. There is a single exception to this rule: an ownership qualifier -may be applied to a substituted template type parameter, which overrides the -ownership qualifier provided by the template argument.

- -

Except as described under -the inference rules, a program is -ill-formed if it attempts to form a pointer or reference type to a -retainable object owner type which lacks an ownership qualifier.

- -

Rationale: these rules, together with the -inference rules, ensure that all objects and lvalues of retainable -object pointer type have an ownership qualifier. The ability to override an ownership qualifier during template substitution is required to counteract the inference of __strong for template type arguments.

- -

There are four ownership qualifiers:

- -
    -
  • __autoreleasing
    • -
  • __strong
    • -
  • __unsafe_unretained
    • -
  • __weak
    • -
- -

A type is nontrivially ownership-qualified -if it is qualified with __autoreleasing, __strong, or -__weak.

- -
-

Spelling

- -

The names of the ownership qualifiers are reserved for the -implementation. A program may not assume that they are or are not -implemented with macros, or what those macros expand to.

- -

An ownership qualifier may be written anywhere that any other type -qualifier may be written.

- -

If an ownership qualifier appears in -the declaration-specifiers, the following rules apply:

- -
    -
  • if the type specifier is a retainable object owner type, the -qualifier applies to that type;
    • -
  • if the outermost non-array part of the declarator is a pointer or -block pointer, the qualifier applies to that type;
    • -
  • otherwise the program is ill-formed.
    • -
- -

If an ownership qualifier appears on the declarator name, or on the -declared object, it is applied to outermost pointer or block-pointer -type.

- -

If an ownership qualifier appears anywhere else in a declarator, it -applies to the type there.

- -
-

Property declarations

- -

A property of retainable object pointer type may have ownership. -If the property's type is ownership-qualified, then the property has -that ownership. If the property has one of the following modifiers, -then the property has the corresponding ownership. A property is -ill-formed if it has conflicting sources of ownership, or if it has -redundant ownership modifiers, or if it has __autoreleasing -ownership.

- -
    -
  • assign implies __unsafe_unretained ownership.
    • -
  • copy implies __strong ownership, as well as the - usual behavior of copy semantics on the setter.
    • -
  • retain implies __strong ownership.
    • -
  • strong implies __strong ownership.
    • -
  • unsafe_unretained implies __unsafe_unretained - ownership.
    • -
  • weak implies __weak ownership.
    • -
- -

With the exception of weak, these modifiers are available -in non-ARC modes.

- -

A property's specified ownership is preserved in its metadata, but -otherwise the meaning is purely conventional unless the property is -synthesized. If a property is synthesized, then the -associated instance variable is the -instance variable which is named, possibly implicitly, by the -@synthesize declaration. If the associated instance variable -already exists, then its ownership qualification must equal the -ownership of the property; otherwise, the instance variable is created -with that ownership qualification.

- -

A property of retainable object pointer type which is synthesized -without a source of ownership has the ownership of its associated -instance variable, if it already exists; otherwise, -[beginning Apple 3.1, -LLVM 3.1] its ownership is implicitly strong. -Prior to this revision, it was ill-formed to synthesize such a -property.

- -

Rationale: using strong by default -is safe and consistent with the generic ARC rule about -inferring ownership. It -is, unfortunately, inconsistent with the non-ARC rule which states -that such properties are implicitly assign. However, that -rule is clearly untenable in ARC, since it leads to default-unsafe -code. The main merit to banning the properties is to avoid confusion -with non-ARC practice, which did not ultimately strike us as -sufficient to justify requiring extra syntax and (more importantly) -forcing novices to understand ownership rules just to declare a -property when the default is so reasonable. Changing the rule away -from non-ARC practice was acceptable because we had conservatively -banned the synthesis in order to give ourselves exactly this -leeway.

- -

Applying __attribute__((NSObject)) to a property not of -retainable object pointer type has the same behavior it does outside -of ARC: it requires the property type to be some sort of pointer and -permits the use of modifiers other than assign. These -modifiers only affect the synthesized getter and setter; direct -accesses to the ivar (even if synthesized) still have primitive -semantics, and the value in the ivar will not be automatically -released during deallocation.

- -
- -
- -
-

Semantics

- -

There are five managed operations which -may be performed on an object of retainable object pointer type. Each -qualifier specifies different semantics for each of these operations. -It is still undefined behavior to access an object outside of its -lifetime.

- -

A load or store with primitive semantics has the same -semantics as the respective operation would have on an void* -lvalue with the same alignment and non-ownership qualification.

- -

Reading occurs when performing a -lvalue-to-rvalue conversion on an object lvalue.

- -
    -
  • For __weak objects, the current pointee is retained and -then released at the end of the current full-expression. This must -execute atomically with respect to assignments and to the final -release of the pointee.
    • -
  • For all other objects, the lvalue is loaded with primitive -semantics.
    • -
- -

Assignment occurs when evaluating -an assignment operator. The semantics vary based on the qualification:

-
    -
  • For __strong objects, the new pointee is first retained; -second, the lvalue is loaded with primitive semantics; third, the new -pointee is stored into the lvalue with primitive semantics; and -finally, the old pointee is released. This is not performed -atomically; external synchronization must be used to make this safe in -the face of concurrent loads and stores.
    • -
  • For __weak objects, the lvalue is updated to point to the -new pointee, unless the new pointee is an object currently undergoing -deallocation, in which case the lvalue is updated to a null pointer. -This must execute atomically with respect to other assignments to the -object, to reads from the object, and to the final release of the new -pointee.
    • -
  • For __unsafe_unretained objects, the new pointee is -stored into the lvalue using primitive semantics.
    • -
  • For __autoreleasing objects, the new pointee is retained, -autoreleased, and stored into the lvalue using primitive semantics.
    • -
- -

Initialization occurs when an object's -lifetime begins, which depends on its storage duration. -Initialization proceeds in two stages:

-
    -
  1. First, a null pointer is stored into the lvalue using primitive -semantics. This step is skipped if the object -is __unsafe_unretained.
    2. -
  2. Second, if the object has an initializer, that expression is -evaluated and then assigned into the object using the usual assignment -semantics.
    3. -
- -

Destruction occurs when an object's -lifetime ends. In all cases it is semantically equivalent to -assigning a null pointer to the object, with the proviso that of -course the object cannot be legally read after the object's lifetime -ends.

- -

Moving occurs in specific situations -where an lvalue is moved from, meaning that its current pointee -will be used but the object may be left in a different (but still -valid) state. This arises with __block variables and rvalue -references in C++. For __strong lvalues, moving is equivalent -to loading the lvalue with primitive semantics, writing a null pointer -to it with primitive semantics, and then releasing the result of the -load at the end of the current full-expression. For all other -lvalues, moving is equivalent to reading the object.

- -
- -
-

Restrictions

- -
-

Weak-unavailable types

- -

It is explicitly permitted for Objective-C classes to not -support __weak references. It is undefined behavior to -perform an operation with weak assignment semantics with a pointer to -an Objective-C object whose class does not support __weak -references.

- -

Rationale: historically, it has been -possible for a class to provide its own reference-count implementation -by overriding retain, release, etc. However, weak -references to an object require coordination with its class's -reference-count implementation because, among other things, weak loads -and stores must be atomic with respect to the final release. -Therefore, existing custom reference-count implementations will -generally not support weak references without additional effort. This -is unavoidable without breaking binary compatibility.

- -

A class may indicate that it does not support weak references by -providing the objc_arc_weak_unavailable attribute on the -class's interface declaration. A retainable object pointer type -is weak-unavailable if is a pointer to an -(optionally protocol-qualified) Objective-C class T -where T or one of its superclasses has -the objc_arc_weak_unavailable attribute. A program is -ill-formed if it applies the __weak ownership qualifier to a -weak-unavailable type or if the value operand of a weak assignment -operation has a weak-unavailable type.

-
- -
-

Storage duration of __autoreleasing objects

- -

A program is ill-formed if it declares an __autoreleasing -object of non-automatic storage duration. A program is ill-formed -if it captures an __autoreleasing object in a block or, -unless by reference, in a C++11 lambda.

- -

Rationale: autorelease pools are tied to the -current thread and scope by their nature. While it is possible to -have temporary objects whose instance variables are filled with -autoreleased objects, there is no way that ARC can provide any sort of -safety guarantee there.

- -

It is undefined behavior if a non-null pointer is assigned to -an __autoreleasing object while an autorelease pool is in -scope and then that object is read after the autorelease pool's scope -is left.

- -
- -
-

Conversion of pointers to ownership-qualified types

- -

A program is ill-formed if an expression of type T* is -converted, explicitly or implicitly, to the type U*, -where T and U have different ownership -qualification, unless:

-
    -
  • T is qualified with __strong, - __autoreleasing, or __unsafe_unretained, and - U is qualified with both const and - __unsafe_unretained; or
    • -
  • either T or U is cv void, where -cv is an optional sequence of non-ownership qualifiers; or
    • -
  • the conversion is requested with a reinterpret_cast in - Objective-C++; or
    • -
  • the conversion is a -well-formed pass-by-writeback.
    • -
- -

The analogous rule applies to T& and U& in -Objective-C++.

- -

Rationale: these rules provide a reasonable -level of type-safety for indirect pointers, as long as the underlying -memory is not deallocated. The conversion to const -__unsafe_unretained is permitted because the semantics of reads -are equivalent across all these ownership semantics, and that's a very -useful and common pattern. The interconversion with void* is -useful for allocating memory or otherwise escaping the type system, -but use it carefully. reinterpret_cast is considered to be -an obvious enough sign of taking responsibility for any -problems.

- -

It is undefined behavior to access an ownership-qualified object -through an lvalue of a differently-qualified type, except that any -non-__weak object may be read through -an __unsafe_unretained lvalue.

- -

It is undefined behavior if a managed operation is performed on -a __strong or __weak object without a guarantee that -it contains a primitive zero bit-pattern, or if the storage for such -an object is freed or reused without the object being first assigned a -null pointer.

- -

Rationale: ARC cannot differentiate between -an assignment operator which is intended to initialize dynamic -memory and one which is intended to potentially replace a value. -Therefore the object's pointer must be valid before letting ARC at it. -Similarly, C and Objective-C do not provide any language hooks for -destroying objects held in dynamic memory, so it is the programmer's -responsibility to avoid leaks (__strong objects) and -consistency errors (__weak objects).

- -

These requirements are followed automatically in Objective-C++ when -creating objects of retainable object owner type with new -or new[] and destroying them with delete, -delete[], or a pseudo-destructor expression. Note that -arrays of nontrivially-ownership-qualified type are not ABI compatible -with non-ARC code because the element type is non-POD: such arrays -that are new[]'d in ARC translation units cannot -be delete[]'d in non-ARC translation units and -vice-versa.

- -
- -
-

Passing to an out parameter by writeback

- -

If the argument passed to a parameter of type -T __autoreleasing * has type U oq *, -where oq is an ownership qualifier, then the argument is a -candidate for pass-by-writeback if:

- -
    -
  • oq is __strong or __weak, and
    • -
  • it would be legal to initialize a T __strong * with -a U __strong *.
    • -
- -

For purposes of overload resolution, an implicit conversion -sequence requiring a pass-by-writeback is always worse than an -implicit conversion sequence not requiring a pass-by-writeback.

- -

The pass-by-writeback is ill-formed if the argument expression does -not have a legal form:

- -
    -
  • &var, where var is a scalar variable of -automatic storage duration with retainable object pointer type
    • -
  • a conditional expression where the second and third operands are -both legal forms
    • -
  • a cast whose operand is a legal form
    • -
  • a null pointer constant
    • -
- -

Rationale: the restriction in the form of -the argument serves two purposes. First, it makes it impossible to -pass the address of an array to the argument, which serves to protect -against an otherwise serious risk of mis-inferring an array -argument as an out-parameter. Second, it makes it much less likely -that the user will see confusing aliasing problems due to the -implementation, below, where their store to the writeback temporary is -not immediately seen in the original argument variable.

- -

A pass-by-writeback is evaluated as follows:

-
    -
  1. The argument is evaluated to yield a pointer p of - type U oq *.
    2. -
  2. If p is a null pointer, then a null pointer is passed as - the argument, and no further work is required for the pass-by-writeback.
    3. -
  3. Otherwise, a temporary of type T __autoreleasing is - created and initialized to a null pointer.
    4. -
  4. If the parameter is not an Objective-C method parameter marked - out, then *p is read, and the result is written - into the temporary with primitive semantics.
    5. -
  5. The address of the temporary is passed as the argument to the - actual call.
    6. -
  6. After the call completes, the temporary is loaded with primitive - semantics, and that value is assigned into *p.
    7. -
- -

Rationale: this is all admittedly -convoluted. In an ideal world, we would see that a local variable is -being passed to an out-parameter and retroactively modify its type to -be __autoreleasing rather than __strong. This would -be remarkably difficult and not always well-founded under the C type -system. However, it was judged unacceptably invasive to require -programmers to write __autoreleasing on all the variables -they intend to use for out-parameters. This was the least bad -solution.

- -
- -
-

Ownership-qualified fields of structs and unions

- -

A program is ill-formed if it declares a member of a C struct or -union to have a nontrivially ownership-qualified type.

- -

Rationale: the resulting type would be -non-POD in the C++ sense, but C does not give us very good language -tools for managing the lifetime of aggregates, so it is more -convenient to simply forbid them. It is still possible to manage this -with a void* or an __unsafe_unretained -object.

- -

This restriction does not apply in Objective-C++. However, -nontrivally ownership-qualified types are considered non-POD: in C++11 -terms, they are not trivially default constructible, copy -constructible, move constructible, copy assignable, move assignable, -or destructible. It is a violation of C++'s One Definition Rule to use -a class outside of ARC that, under ARC, would have a nontrivially -ownership-qualified member.

- -

Rationale: unlike in C, we can express all -the necessary ARC semantics for ownership-qualified subobjects as -suboperations of the (default) special member functions for the class. -These functions then become non-trivial. This has the non-obvious -result that the class will have a non-trivial copy constructor and -non-trivial destructor; if this would not normally be true outside of -ARC, objects of the type will be passed and returned in an -ABI-incompatible manner.

- -
- -
- -
-

Ownership inference

- -
-

Objects

- -

If an object is declared with retainable object owner type, but -without an explicit ownership qualifier, its type is implicitly -adjusted to have __strong qualification.

- -

As a special case, if the object's base type is Class -(possibly protocol-qualified), the type is adjusted to -have __unsafe_unretained qualification instead.

- -
- -
-

Indirect parameters

- -

If a function or method parameter has type T*, where -T is an ownership-unqualified retainable object pointer type, -then:

- -
    -
  • if T is const-qualified or Class, then -it is implicitly qualified with __unsafe_unretained;
    • -
  • otherwise, it is implicitly qualified -with __autoreleasing.
    • -
- -

Rationale: __autoreleasing exists -mostly for this case, the Cocoa convention for out-parameters. Since -a pointer to const is obviously not an out-parameter, we -instead use a type more useful for passing arrays. If the user -instead intends to pass in a mutable array, inferring -__autoreleasing is the wrong thing to do; this directs some -of the caution in the following rules about writeback.

- -

Such a type written anywhere else would be ill-formed by the -general rule requiring ownership qualifiers.

- -

This rule does not apply in Objective-C++ if a parameter's type is -dependent in a template pattern and is only instantiated to -a type which would be a pointer to an unqualified retainable object -pointer type. Such code is still ill-formed.

- -

Rationale: the convention is very unlikely -to be intentional in template code.

- -
- -
-

Template arguments

- -

If a template argument for a template type parameter is an -retainable object owner type that does not have an explicit ownership -qualifier, it is adjusted to have __strong -qualification. This adjustment occurs regardless of whether the -template argument was deduced or explicitly specified.

- -

Rationale: __strong is a useful default for containers (e.g., std::vector<id>), which would otherwise require explicit qualification. Moreover, unqualified retainable object pointer types are unlikely to be useful within templates, since they generally need to have a qualifier applied to the before being used.

- -
-
-
- - -
-

Method families

- -

An Objective-C method may fall into a method -family, which is a conventional set of behaviors ascribed to it -by the Cocoa conventions.

- -

A method is in a certain method family if:

-
    -
  • it has a objc_method_family attribute placing it in that - family; or if not that,
    • -
  • it does not have an objc_method_family attribute placing - it in a different or no family, and
    • -
  • its selector falls into the corresponding selector family, and
    • -
  • its signature obeys the added restrictions of the method family.
    • -
- -

A selector is in a certain selector family if, ignoring any leading -underscores, the first component of the selector either consists -entirely of the name of the method family or it begins with that name -followed by a character other than a lowercase letter. For -example, _perform:with: and performWith: would fall -into the perform family (if we recognized one), -but performing:with would not.

- -

The families and their added restrictions are:

- -
    -
  • alloc methods must return a retainable object pointer type.
    • -
  • copy methods must return a retainable object pointer type.
    • -
  • mutableCopy methods must return a retainable object pointer type.
    • -
  • new methods must return a retainable object pointer type.
    • -
  • init methods must be instance methods and must return an -Objective-C pointer type. Additionally, a program is ill-formed if it -declares or contains a call to an init method whose return -type is neither id nor a pointer to a super-class or -sub-class of the declaring class (if the method was declared on -a class) or the static receiver type of the call (if it was declared -on a protocol). - -

    Rationale: there are a fair number of existing -methods with init-like selectors which nonetheless don't -follow the init conventions. Typically these are either -accidental naming collisions or helper methods called during -initialization. Because of the peculiar retain/release behavior -of init methods, it's very important not to treat these -methods as init methods if they aren't meant to be. It was -felt that implicitly defining these methods out of the family based on -the exact relationship between the return type and the declaring class -would be much too subtle and fragile. Therefore we identify a small -number of legitimate-seeming return types and call everything else an -error. This serves the secondary purpose of encouraging programmers -not to accidentally give methods names in the init family.

    - -

    Note that a method with an init-family selector which -returns a non-Objective-C type (e.g. void) is perfectly -well-formed; it simply isn't in the init family.

    -
    • -
- -

A program is ill-formed if a method's declarations, -implementations, and overrides do not all have the same method -family.

- -
-

Explicit method family control

- -

A method may be annotated with the objc_method_family -attribute to precisely control which method family it belongs to. If -a method in an @implementation does not have this attribute, -but there is a method declared in the corresponding @interface -that does, then the attribute is copied to the declaration in the -@implementation. The attribute is available outside of ARC, -and may be tested for with the preprocessor query -__has_attribute(objc_method_family).

- -

The attribute is spelled -__attribute__((objc_method_family(family))). -If family is none, the method has no family, even if -it would otherwise be considered to have one based on its selector and -type. Otherwise, family must be one -of alloc, copy, init, -mutableCopy, or new, in which case the method is -considered to belong to the corresponding family regardless of its -selector. It is an error if a method that is explicitly added to a -family in this way does not meet the requirements of the family other -than the selector naming convention.

- -

Rationale: the rules codified in this document -describe the standard conventions of Objective-C. However, as these -conventions have not heretofore been enforced by an unforgiving -mechanical system, they are only imperfectly kept, especially as they -haven't always even been precisely defined. While it is possible to -define low-level ownership semantics with attributes like -ns_returns_retained, this attribute allows the user to -communicate semantic intent, which is of use both to ARC (which, e.g., -treats calls to init specially) and the static analyzer.

-
- -
-

Semantics of method families

- -

A method's membership in a method family may imply non-standard -semantics for its parameters and return type.

- -

Methods in the alloc, copy, mutableCopy, -and new families — that is, methods in all the -currently-defined families except init — implicitly -return a retained -object as if they were annotated with -the ns_returns_retained attribute. This can be overridden by -annotating the method with either of -the ns_returns_autoreleased or -ns_returns_not_retained attributes.

- -

Properties also follow same naming rules as methods. This means that -those in the alloc, copy, mutableCopy, -and new families provide access to -retained objects. -This can be overridden by annotating the property with -ns_returns_not_retained attribute.

- -
-

Semantics of init

-

Methods in the init family implicitly -consume their self -parameter and return a -retained object. Neither of these properties can be altered -through attributes.

- -

A call to an init method with a receiver that is either -self (possibly parenthesized or casted) or super is -called a delegate init call. It is an error -for a delegate init call to be made except from an init -method, and excluding blocks within such methods.

- -

As an exception to the usual rule, the -variable self is mutable in an init method and has -the usual semantics for a __strong variable. However, it is -undefined behavior and the program is ill-formed, no diagnostic -required, if an init method attempts to use the previous -value of self after the completion of a delegate init call. -It is conventional, but not required, for an init method to -return self.

- -

It is undefined behavior for a program to cause two or more calls -to init methods on the same object, except that -each init method invocation may perform at most one delegate -init call.

- -
- -
-

Related result types

- -

Certain methods are candidates to have related -result types:

-
    -
  • class methods in the alloc and new method families
    • -
  • instance methods in the init family
    • -
  • the instance method self
    • -
  • outside of ARC, the instance methods retain and autorelease
    • -
- -

If the formal result type of such a method is id or -protocol-qualified id, or a type equal to the declaring class -or a superclass, then it is said to have a related result type. In -this case, when invoked in an explicit message send, it is assumed to -return a type related to the type of the receiver:

- -
    -
  • if it is a class method, and the receiver is a class -name T, the message send expression has type T*; -otherwise
    • -
  • if it is an instance method, and the receiver has type T, -the message send expression has type T; otherwise
    • -
  • the message send expression has the normal result type of the -method.
    • -
- -

This is a new rule of the Objective-C language and applies outside -of ARC.

- -

Rationale: ARC's automatic code emission is -more prone than most code to signature errors, i.e. errors where a -call was emitted against one method signature, but the implementing -method has an incompatible signature. Having more precise type -information helps drastically lower this risk, as well as catching -a number of latent bugs.

- -
-
-
- -
-

Optimization

- -

ARC applies aggressive rules for the optimization of local -behavior. These rules are based around a core assumption of -local balancing: that other code will -perform retains and releases as necessary (and only as necessary) for -its own safety, and so the optimizer does not need to consider global -properties of the retain and release sequence. For example, if a -retain and release immediately bracket a call, the optimizer can -delete the retain and release on the assumption that the called -function will not do a constant number of unmotivated releases -followed by a constant number of balancing retains, such that -the local retain/release pair is the only thing preventing the called -function from ending up with a dangling reference.

- -

The optimizer assumes that when a new value enters local control, -e.g. from a load of a non-local object or as the result of a function -call, it is instaneously valid. Subsequently, a retain and release of -a value are necessary on a computation path only if there is a use of -that value before the release and after any operation which might -cause a release of the value (including indirectly or non-locally), -and only if the value is not demonstrably already retained.

- -

The complete optimization rules are quite complicated, but it would -still be useful to document them here.

- -
-

Precise lifetime semantics

- -

In general, ARC maintains an invariant that a retainable object -pointer held in a __strong object will be retained for the -full formal lifetime of the object. Objects subject to this invariant -have precise lifetime semantics.

- -

By default, local variables of automatic storage duration do not -have precise lifetime semantics. Such objects are simply strong -references which hold values of retainable object pointer type, and -these values are still fully subject to the optimizations on values -under local control.

- -

Rationale: applying these precise-lifetime -semantics strictly would be prohibitive. Many useful optimizations -that might theoretically decrease the lifetime of an object would be -rendered impossible. Essentially, it promises too much.

- -

A local variable of retainable object owner type and automatic -storage duration may be annotated with the objc_precise_lifetime -attribute to indicate that it should be considered to be an object -with precise lifetime semantics.

- -

Rationale: nonetheless, it is sometimes -useful to be able to force an object to be released at a precise time, -even if that object does not appear to be used. This is likely to be -uncommon enough that the syntactic weight of explicitly requesting -these semantics will not be burdensome, and may even make the code -clearer.

- -
- -
- -
-

Miscellaneous

- -
-

Special methods

- -
-

Memory management methods

- -

A program is ill-formed if it contains a method definition, message -send, or @selector expression for any of the following -selectors:

-
    -
  • autorelease
    • -
  • release
    • -
  • retain
    • -
  • retainCount
    • -
- -

Rationale: retainCount is banned -because ARC robs it of consistent semantics. The others were banned -after weighing three options for how to deal with message sends:

- -

Honoring them would work out very poorly if a programmer -naively or accidentally tried to incorporate code written for manual -retain/release code into an ARC program. At best, such code would do -twice as much work as necessary; quite frequently, however, ARC and -the explicit code would both try to balance the same retain, leading -to crashes. The cost is losing the ability to perform unrooted -retains, i.e. retains not logically corresponding to a strong -reference in the object graph.

- -

Ignoring them would badly violate user expectations about their -code. While it would make it easier to develop code simultaneously -for ARC and non-ARC, there is very little reason to do so except for -certain library developers. ARC and non-ARC translation units share -an execution model and can seamlessly interoperate. Within a -translation unit, a developer who faithfully maintains their code in -non-ARC mode is suffering all the restrictions of ARC for zero -benefit, while a developer who isn't testing the non-ARC mode is -likely to be unpleasantly surprised if they try to go back to it.

- -

Banning them has the disadvantage of making it very awkward -to migrate existing code to ARC. The best answer to that, given a -number of other changes and restrictions in ARC, is to provide a -specialized tool to assist users in that migration.

- -

Implementing these methods was banned because they are too integral -to the semantics of ARC; many tricks which worked tolerably under -manual reference counting will misbehave if ARC performs an ephemeral -extra retain or two. If absolutely required, it is still possible to -implement them in non-ARC code, for example in a category; the -implementations must obey the semantics -laid out elsewhere in this document.

- -
-
- -
-

dealloc

- -

A program is ill-formed if it contains a message send -or @selector expression for the selector dealloc.

- -

Rationale: there are no legitimate reasons -to call dealloc directly.

- -

A class may provide a method definition for an instance method -named dealloc. This method will be called after the final -release of the object but before it is deallocated or any of -its instance variables are destroyed. The superclass's implementation -of dealloc will be called automatically when the method -returns.

- -

Rationale: even though ARC destroys instance -variables automatically, there are still legitimate reasons to write -a dealloc method, such as freeing non-retainable resources. -Failing to call [super dealloc] in such a method is nearly -always a bug. Sometimes, the object is simply trying to prevent -itself from being destroyed, but dealloc is really far too -late for the object to be raising such objections. Somewhat more -legitimately, an object may have been pool-allocated and should not be -deallocated with free; for now, this can only be supported -with a dealloc implementation outside of ARC. Such an -implementation must be very careful to do all the other work -that NSObject's dealloc would, which is outside the -scope of this document to describe.

- -

The instance variables for an ARC-compiled class will be destroyed -at some point after control enters the dealloc method for the -root class of the class. The ordering of the destruction of instance -variables is unspecified, both within a single class and between -subclasses and superclasses.

- -

Rationale: the traditional, non-ARC pattern -for destroying instance variables is to destroy them immediately -before calling [super dealloc]. Unfortunately, message -sends from the superclass are quite capable of reaching methods in the -subclass, and those methods may well read or write to those instance -variables. Making such message sends from dealloc is generally -discouraged, since the subclass may well rely on other invariants that -were broken during dealloc, but it's not so inescapably -dangerous that we felt comfortable calling it undefined behavior. -Therefore we chose to delay destroying the instance variables to a -point at which message sends are clearly disallowed: the point at -which the root class's deallocation routines take over.

- -

In most code, the difference is not observable. It can, however, -be observed if an instance variable holds a strong reference to an -object whose deallocation will trigger a side-effect which must be -carefully ordered with respect to the destruction of the super class. -Such code violates the design principle that semantically important -behavior should be explicit. A simple fix is to clear the instance -variable manually during dealloc; a more holistic solution is -to move semantically important side-effects out of -dealloc and into a separate teardown phase which can rely on -working with well-formed objects.

- -
- -
- -
-

@autoreleasepool

- -

To simplify the use of autorelease pools, and to bring them under -the control of the compiler, a new kind of statement is available in -Objective-C. It is written @autoreleasepool followed by -a compound-statement, i.e. by a new scope delimited by curly -braces. Upon entry to this block, the current state of the -autorelease pool is captured. When the block is exited normally, -whether by fallthrough or directed control flow (such -as return or break), the autorelease pool is -restored to the saved state, releasing all the objects in it. When -the block is exited with an exception, the pool is not drained.

- -

@autoreleasepool may be used in non-ARC translation units, -with equivalent semantics.

- -

A program is ill-formed if it refers to the -NSAutoreleasePool class.

- -

Rationale: autorelease pools are clearly -important for the compiler to reason about, but it is far too much to -expect the compiler to accurately reason about control dependencies -between two calls. It is also very easy to accidentally forget to -drain an autorelease pool when using the manual API, and this can -significantly inflate the process's high-water-mark. The introduction -of a new scope is unfortunate but basically required for sane -interaction with the rest of the language. Not draining the pool -during an unwind is apparently required by the Objective-C exceptions -implementation.

- -
- -
-

self

- -

The self parameter variable of an Objective-C method is -never actually retained by the implementation. It is undefined -behavior, or at least dangerous, to cause an object to be deallocated -during a message send to that object.

- -

To make this safe, for Objective-C instance methods self is -implicitly const unless the method is in the init family. Further, self -is always implicitly const within a class method.

- -

Rationale: the cost of -retaining self in all methods was found to be prohibitive, as -it tends to be live across calls, preventing the optimizer from -proving that the retain and release are unnecessary — for good -reason, as it's quite possible in theory to cause an object to be -deallocated during its execution without this retain and release. -Since it's extremely uncommon to actually do so, even unintentionally, -and since there's no natural way for the programmer to remove this -retain/release pair otherwise (as there is for other parameters by, -say, making the variable __unsafe_unretained), we chose to -make this optimizing assumption and shift some amount of risk to the -user.

- -
- -
-

Fast enumeration iteration variables

- -

If a variable is declared in the condition of an Objective-C fast -enumeration loop, and the variable has no explicit ownership -qualifier, then it is qualified with const __strong and -objects encountered during the enumeration are not actually -retained.

- -

Rationale: this is an optimization made -possible because fast enumeration loops promise to keep the objects -retained during enumeration, and the collection itself cannot be -synchronously modified. It can be overridden by explicitly qualifying -the variable with __strong, which will make the variable -mutable again and cause the loop to retain the objects it -encounters.

- -
- -
-

Blocks

- -

The implicit const capture variables created when -evaluating a block literal expression have the same ownership -semantics as the local variables they capture. The capture is -performed by reading from the captured variable and initializing the -capture variable with that value; the capture variable is destroyed -when the block literal is, i.e. at the end of the enclosing scope.

- -

The inference rules apply -equally to __block variables, which is a shift in semantics -from non-ARC, where __block variables did not implicitly -retain during capture.

- -

__block variables of retainable object owner type are -moved off the stack by initializing the heap copy with the result of -moving from the stack copy.

- -

With the exception of retains done as part of initializing -a __strong parameter variable or reading a __weak -variable, whenever these semantics call for retaining a value of -block-pointer type, it has the effect of a Block_copy. The -optimizer may remove such copies when it sees that the result is -used only as an argument to a call.

- -
- -
-

Exceptions

- -

By default in Objective C, ARC is not exception-safe for normal -releases:

-
    -
  • It does not end the lifetime of __strong variables when -their scopes are abnormally terminated by an exception.
    • -
  • It does not perform releases which would occur at the end of -a full-expression if that full-expression throws an exception.
    • -
- -

A program may be compiled with the option --fobjc-arc-exceptions in order to enable these, or with the -option -fno-objc-arc-exceptions to explicitly disable them, -with the last such argument winning.

- -

Rationale: the standard Cocoa convention is -that exceptions signal programmer error and are not intended to be -recovered from. Making code exceptions-safe by default would impose -severe runtime and code size penalties on code that typically does not -actually care about exceptions safety. Therefore, ARC-generated code -leaks by default on exceptions, which is just fine if the process is -going to be immediately terminated anyway. Programs which do care -about recovering from exceptions should enable the option.

- -

In Objective-C++, -fobjc-arc-exceptions is enabled by -default.

- -

Rationale: C++ already introduces pervasive -exceptions-cleanup code of the sort that ARC introduces. C++ -programmers who have not already disabled exceptions are much more -likely to actual require exception-safety.

- -

ARC does end the lifetimes of __weak objects when an -exception terminates their scope unless exceptions are disabled in the -compiler.

- -

Rationale: the consequence of a -local __weak object not being destroyed is very likely to be -corruption of the Objective-C runtime, so we want to be safer here. -Of course, potentially massive leaks are about as likely to take down -the process as this corruption is if the program does try to recover -from exceptions.

- -
- -
-

Interior pointers

- -

An Objective-C method returning a non-retainable pointer may be -annotated with the objc_returns_inner_pointer attribute to -indicate that it returns a handle to the internal data of an object, -and that this reference will be invalidated if the object is -destroyed. When such a message is sent to an object, the object's -lifetime will be extended until at least the earliest of:

- -
    -
  • the last use of the returned pointer, or any pointer derived from -it, in the calling function or
    • -
  • the autorelease pool is restored to a previous state.
    • -
- -

Rationale: not all memory and resources are -managed with reference counts; it is common for objects to manage -private resources in their own, private way. Typically these -resources are completely encapsulated within the object, but some -classes offer their users direct access for efficiency. If ARC is not -aware of methods that return such interior pointers, its -optimizations can cause the owning object to be reclaimed too soon. -This attribute informs ARC that it must tread lightly.

- -

The extension rules are somewhat intentionally vague. The -autorelease pool limit is there to permit a simple implementation to -simply retain and autorelease the receiver. The other limit permits -some amount of optimization. The phrase derived from is -intended to encompass the results both of pointer transformations, -such as casts and arithmetic, and of loading from such derived -pointers; furthermore, it applies whether or not such derivations are -applied directly in the calling code or by other utility code (for -example, the C library routine strchr). However, the -implementation never need account for uses after a return from the -code which calls the method returning an interior pointer.

- -

As an exception, no extension is required if the receiver is loaded -directly from a __strong object -with precise lifetime semantics.

- -

Rationale: implicit autoreleases carry the -risk of significantly inflating memory use, so it's important to -provide users a way of avoiding these autoreleases. Tying this to -precise lifetime semantics is ideal, as for local variables this -requires a very explicit annotation, which allows ARC to trust the -user with good cheer.

- -
- -
-

C retainable pointer types

- -

A type is a C retainable pointer type -if it is a pointer to (possibly qualified) void or a -pointer to a (possibly qualifier) struct or class -type.

- -

Rationale: ARC does not manage pointers of -CoreFoundation type (or any of the related families of retainable C -pointers which interoperate with Objective-C for retain/release -operation). In fact, ARC does not even know how to distinguish these -types from arbitrary C pointer types. The intent of this concept is -to filter out some obviously non-object types while leaving a hook for -later tightening if a means of exhaustively marking CF types is made -available.

- -
-

Auditing of C retainable pointer interfaces

- -

[beginning Apple 4.0, LLVM 3.1]

- -

A C function may be marked with the cf_audited_transfer -attribute to express that, except as otherwise marked with attributes, -it obeys the parameter (consuming vs. non-consuming) and return -(retained vs. non-retained) conventions for a C function of its name, -namely:

- -
    -
  • A parameter of C retainable pointer type is assumed to not be -consumed unless it is marked with the cf_consumed attribute, and
    • -
  • A result of C retainable pointer type is assumed to not be -returned retained unless the function is either -marked cf_returns_retained or it follows -the create/copy naming convention and is not -marked cf_returns_not_retained.
    • -
- -

A function obeys the create/copy naming -convention if its name contains as a substring:

-
    -
  • either Create or Copy not followed by a lowercase letter, or
    • -
  • either create or copy not followed by a lowercase -letter and not preceded by any letter, whether uppercase or lowercase.
    • -
- -

A second attribute, cf_unknown_transfer, signifies that a -function's transfer semantics cannot be accurately captured using any -of these annotations. A program is ill-formed if it annotates the -same function with both cf_audited_transfer -and cf_unknown_transfer.

- -

A pragma is provided to facilitate the mass annotation of interfaces:

- -
#pragma clang arc_cf_code_audited begin
-...
-#pragma clang arc_cf_code_audited end
- -

All C functions declared within the extent of this pragma are -treated as if annotated with the cf_audited_transfer -attribute unless they otherwise have the cf_unknown_transfer -attribute. The pragma is accepted in all language modes. A program -is ill-formed if it attempts to change files, whether by including a -file or ending the current file, within the extent of this pragma.

- -

It is possible to test for all the features in this section with -__has_feature(arc_cf_code_audited).

- -

Rationale: A significant inconvenience in -ARC programming is the necessity of interacting with APIs based around -C retainable pointers. These features are designed to make it -relatively easy for API authors to quickly review and annotate their -interfaces, in turn improving the fidelity of tools such as the static -analyzer and ARC. The single-file restriction on the pragma is -designed to eliminate the risk of accidentally annotating some other -header's interfaces.

- -
- -
- -
- -
-

Runtime support

- -

This section describes the interaction between the ARC runtime and -the code generated by the ARC compiler. This is not part of the ARC -language specification; instead, it is effectively a language-specific -ABI supplement, akin to the Itanium generic ABI for C++.

- -

Ownership qualification does not alter the storage requirements for -objects, except that it is undefined behavior if a __weak -object is inadequately aligned for an object of type id. The -other qualifiers may be used on explicitly under-aligned memory.

- -

The runtime tracks __weak objects which holds non-null -values. It is undefined behavior to direct modify a __weak -object which is being tracked by the runtime except through an -objc_storeWeak, -objc_destroyWeak, -or objc_moveWeak -call.

- -

The runtime must provide a number of new entrypoints which the -compiler may emit, which are described in the remainder of this -section.

- -

Rationale: Several of these functions are -semantically equivalent to a message send; we emit calls to C -functions instead because:

-
    -
  • the machine code to do so is significantly smaller,
    • -
  • it is much easier to recognize the C functions in the ARC optimizer, and
    • -
  • a sufficient sophisticated runtime may be able to avoid the -message send in common cases.
    • -
- -

Several other of these functions are fused operations which -can be described entirely in terms of other operations. We use the -fused operations primarily as a code-size optimization, although in -some cases there is also a real potential for avoiding redundant -operations in the runtime.

- -
- -
-

id objc_autorelease(id value);

-

Precondition: value is null or a pointer to a -valid object.

-

If value is null, this call has no effect. Otherwise, it -adds the object to the innermost autorelease pool exactly as if the -object had been sent the autorelease message.

-

Always returns value.

-
- -
-

void objc_autoreleasePoolPop(void *pool);

-

Precondition: pool is the result of a previous call to -objc_autoreleasePoolPush -on the current thread, where neither pool nor any enclosing -pool have previously been popped.

-

Releases all the objects added to the given autorelease pool and -any autorelease pools it encloses, then sets the current autorelease -pool to the pool directly enclosing pool.

-
- -
-

void *objc_autoreleasePoolPush(void);

-

Creates a new autorelease pool that is enclosed by the current -pool, makes that the current pool, and returns an opaque handle -to it.

- -

Rationale: while the interface is described -as an explicit hierarchy of pools, the rules allow the implementation -to just keep a stack of objects, using the stack depth as the opaque -pool handle.

- -
- -
-

id objc_autoreleaseReturnValue(id value);

-

Precondition: value is null or a pointer to a -valid object.

-

If value is null, this call has no effect. Otherwise, it -makes a best effort to hand off ownership of a retain count on the -object to a call -to objc_retainAutoreleasedReturnValue -for the same object in an enclosing call frame. If this is not -possible, the object is autoreleased as above.

-

Always returns value.

-
- -
-

void objc_copyWeak(id *dest, id *src);

-

Precondition: src is a valid pointer which either -contains a null pointer or has been registered as a __weak -object. dest is a valid pointer which has not been -registered as a __weak object.

-

dest is initialized to be equivalent to src, -potentially registering it with the runtime. Equivalent to the -following code:

-
void objc_copyWeak(id *dest, id *src) {
-  objc_release(objc_initWeak(dest, objc_loadWeakRetained(src)));
-}
-

Must be atomic with respect to calls to objc_storeWeak -on src.

-
- -
-

void objc_destroyWeak(id *object);

-

Precondition: object is a valid pointer which -either contains a null pointer or has been registered as -a __weak object.

-

object is unregistered as a weak object, if it ever was. -The current value of object is left unspecified; otherwise, -equivalent to the following code:

-
void objc_destroyWeak(id *object) {
-  objc_storeWeak(object, nil);
-}
-

Does not need to be atomic with respect to calls -to objc_storeWeak on object.

-
- -
-

id objc_initWeak(id *object, id value);

-

Precondition: object is a valid pointer which has -not been registered as a __weak object. value is -null or a pointer to a valid object.

-

If value is a null pointer or the object to which it -points has begun deallocation, object is zero-initialized. -Otherwise, object is registered as a __weak object -pointing to value. Equivalent to the following code:

-
id objc_initWeak(id *object, id value) {
-  *object = nil;
-  return objc_storeWeak(object, value);
-}
-

Returns the value of object after the call.

-

Does not need to be atomic with respect to calls -to objc_storeWeak on object.

-
- -
-

id objc_loadWeak(id *object);

-

Precondition: object is a valid pointer which -either contains a null pointer or has been registered as -a __weak object.

-

If object is registered as a __weak object, and -the last value stored into object has not yet been -deallocated or begun deallocation, retains and autoreleases that value -and returns it. Otherwise returns null. Equivalent to the following -code:

-
id objc_loadWeak(id *object) {
-  return objc_autorelease(objc_loadWeakRetained(object));
-}
-

Must be atomic with respect to calls to objc_storeWeak -on object.

-
Rationale: loading weak references would be -inherently prone to race conditions without the retain.
-
- -
-

id objc_loadWeakRetained(id *object);

-

Precondition: object is a valid pointer which -either contains a null pointer or has been registered as -a __weak object.

-

If object is registered as a __weak object, and -the last value stored into object has not yet been -deallocated or begun deallocation, retains that value and returns it. -Otherwise returns null.

-

Must be atomic with respect to calls to objc_storeWeak -on object.

-
- -
-

void objc_moveWeak(id *dest, id *src);

-

Precondition: src is a valid pointer which either -contains a null pointer or has been registered as a __weak -object. dest is a valid pointer which has not been -registered as a __weak object.

-

dest is initialized to be equivalent to src, -potentially registering it with the runtime. src may then be -left in its original state, in which case this call is equivalent -to objc_copyWeak, or it -may be left as null.

-

Must be atomic with respect to calls to objc_storeWeak -on src.

-
- -
-

void objc_release(id value);

-

Precondition: value is null or a pointer to a -valid object.

-

If value is null, this call has no effect. Otherwise, it -performs a release operation exactly as if the object had been sent -the release message.

-
- -
-

id objc_retain(id value);

-

Precondition: value is null or a pointer to a -valid object.

-

If value is null, this call has no effect. Otherwise, it -performs a retain operation exactly as if the object had been sent -the retain message.

-

Always returns value.

-
- -
-

id objc_retainAutorelease(id value);

-

Precondition: value is null or a pointer to a -valid object.

-

If value is null, this call has no effect. Otherwise, it -performs a retain operation followed by an autorelease operation. -Equivalent to the following code:

-
id objc_retainAutorelease(id value) {
-  return objc_autorelease(objc_retain(value));
-}
-

Always returns value.

-
- -
-

id objc_retainAutoreleaseReturnValue(id value);

-

Precondition: value is null or a pointer to a -valid object.

-

If value is null, this call has no effect. Otherwise, it -performs a retain operation followed by the operation described in -objc_autoreleaseReturnValue. -Equivalent to the following code:

-
id objc_retainAutoreleaseReturnValue(id value) {
-  return objc_autoreleaseReturnValue(objc_retain(value));
-}
-

Always returns value.

-
- -
-

id objc_retainAutoreleasedReturnValue(id value);

-

Precondition: value is null or a pointer to a -valid object.

-

If value is null, this call has no effect. Otherwise, it -attempts to accept a hand off of a retain count from a call to -objc_autoreleaseReturnValue -on value in a recently-called function or something it -calls. If that fails, it performs a retain operation exactly -like objc_retain.

-

Always returns value.

-
- -
-

id objc_retainBlock(id value);

-

Precondition: value is null or a pointer to a -valid block object.

-

If value is null, this call has no effect. Otherwise, if -the block pointed to by value is still on the stack, it is -copied to the heap and the address of the copy is returned. Otherwise -a retain operation is performed on the block exactly as if it had been -sent the retain message.

-
- -
-

id objc_storeStrong(id *object, id value);

-

Precondition: object is a valid pointer to -a __strong object which is adequately aligned for a -pointer. value is null or a pointer to a valid object.

-

Performs the complete sequence for assigning to a __strong -object of non-block type. Equivalent to the following code:

-
id objc_storeStrong(id *object, id value) {
-  value = [value retain];
-  id oldValue = *object;
-  *object = value;
-  [oldValue release];
-  return value;
-}
-

Always returns value.

-
- -
-

id objc_storeWeak(id *object, id value);

-

Precondition: object is a valid pointer which -either contains a null pointer or has been registered as -a __weak object. value is null or a pointer to a -valid object.

-

If value is a null pointer or the object to which it -points has begun deallocation, object is assigned null -and unregistered as a __weak object. Otherwise, -object is registered as a __weak object or has its -registration updated to point to value.

-

Returns the value of object after the call.

-
- -
-
- - diff --git a/docs/AutomaticReferenceCounting.rst b/docs/AutomaticReferenceCounting.rst new file mode 100644 index 000000000000..1457b6082d15 --- /dev/null +++ b/docs/AutomaticReferenceCounting.rst @@ -0,0 +1,2283 @@ +.. FIXME: move to the stylesheet or Sphinx plugin + +.. raw:: html + + + +.. role:: arc-term +.. role:: revision +.. role:: when-revised + +============================================== +Objective-C Automatic Reference Counting (ARC) +============================================== + +.. contents:: + :local: + +.. _arc.meta: + +About this document +=================== + +.. _arc.meta.purpose: + +Purpose +------- + +The first and primary purpose of this document is to serve as a complete +technical specification of Automatic Reference Counting. Given a core +Objective-C compiler and runtime, it should be possible to write a compiler and +runtime which implements these new semantics. + +The secondary purpose is to act as a rationale for why ARC was designed in this +way. This should remain tightly focused on the technical design and should not +stray into marketing speculation. + +.. _arc.meta.background: + +Background +---------- + +This document assumes a basic familiarity with C. + +:arc-term:`Blocks` are a C language extension for creating anonymous functions. +Users interact with and transfer block objects using :arc-term:`block +pointers`, which are represented like a normal pointer. A block may capture +values from local variables; when this occurs, memory must be dynamically +allocated. The initial allocation is done on the stack, but the runtime +provides a ``Block_copy`` function which, given a block pointer, either copies +the underlying block object to the heap, setting its reference count to 1 and +returning the new block pointer, or (if the block object is already on the +heap) increases its reference count by 1. The paired function is +``Block_release``, which decreases the reference count by 1 and destroys the +object if the count reaches zero and is on the heap. + +Objective-C is a set of language extensions, significant enough to be +considered a different language. It is a strict superset of C. The extensions +can also be imposed on C++, producing a language called Objective-C++. The +primary feature is a single-inheritance object system; we briefly describe the +modern dialect. + +Objective-C defines a new type kind, collectively called the :arc-term:`object +pointer types`. This kind has two notable builtin members, ``id`` and +``Class``; ``id`` is the final supertype of all object pointers. The validity +of conversions between object pointer types is not checked at runtime. Users +may define :arc-term:`classes`; each class is a type, and the pointer to that +type is an object pointer type. A class may have a superclass; its pointer +type is a subtype of its superclass's pointer type. A class has a set of +:arc-term:`ivars`, fields which appear on all instances of that class. For +every class *T* there's an associated metaclass; it has no fields, its +superclass is the metaclass of *T*'s superclass, and its metaclass is a global +class. Every class has a global object whose class is the class's metaclass; +metaclasses have no associated type, so pointers to this object have type +``Class``. + +A class declaration (``@interface``) declares a set of :arc-term:`methods`. A +method has a return type, a list of argument types, and a :arc-term:`selector`: +a name like ``foo:bar:baz:``, where the number of colons corresponds to the +number of formal arguments. A method may be an instance method, in which case +it can be invoked on objects of the class, or a class method, in which case it +can be invoked on objects of the metaclass. A method may be invoked by +providing an object (called the :arc-term:`receiver`) and a list of formal +arguments interspersed with the selector, like so: + +.. code-block:: objc + + [receiver foo: fooArg bar: barArg baz: bazArg] + +This looks in the dynamic class of the receiver for a method with this name, +then in that class's superclass, etc., until it finds something it can execute. +The receiver "expression" may also be the name of a class, in which case the +actual receiver is the class object for that class, or (within method +definitions) it may be ``super``, in which case the lookup algorithm starts +with the static superclass instead of the dynamic class. The actual methods +dynamically found in a class are not those declared in the ``@interface``, but +those defined in a separate ``@implementation`` declaration; however, when +compiling a call, typechecking is done based on the methods declared in the +``@interface``. + +Method declarations may also be grouped into :arc-term:`protocols`, which are not +inherently associated with any class, but which classes may claim to follow. +Object pointer types may be qualified with additional protocols that the object +is known to support. + +:arc-term:`Class extensions` are collections of ivars and methods, designed to +allow a class's ``@interface`` to be split across multiple files; however, +there is still a primary implementation file which must see the +``@interface``\ s of all class extensions. :arc-term:`Categories` allow +methods (but not ivars) to be declared *post hoc* on an arbitrary class; the +methods in the category's ``@implementation`` will be dynamically added to that +class's method tables which the category is loaded at runtime, replacing those +methods in case of a collision. + +In the standard environment, objects are allocated on the heap, and their +lifetime is manually managed using a reference count. This is done using two +instance methods which all classes are expected to implement: ``retain`` +increases the object's reference count by 1, whereas ``release`` decreases it +by 1 and calls the instance method ``dealloc`` if the count reaches 0. To +simplify certain operations, there is also an :arc-term:`autorelease pool`, a +thread-local list of objects to call ``release`` on later; an object can be +added to this pool by calling ``autorelease`` on it. + +Block pointers may be converted to type ``id``; block objects are laid out in a +way that makes them compatible with Objective-C objects. There is a builtin +class that all block objects are considered to be objects of; this class +implements ``retain`` by adjusting the reference count, not by calling +``Block_copy``. + +.. _arc.meta.evolution: + +Evolution +--------- + +ARC is under continual evolution, and this document must be updated as the +language progresses. + +If a change increases the expressiveness of the language, for example by +lifting a restriction or by adding new syntax, the change will be annotated +with a revision marker, like so: + + ARC applies to Objective-C pointer types, block pointer types, and + :when-revised:`[beginning Apple 8.0, LLVM 3.8]` :revision:`BPTRs declared + within` ``extern "BCPL"`` blocks. + +For now, it is sensible to version this document by the releases of its sole +implementation (and its host project), clang. "LLVM X.Y" refers to an +open-source release of clang from the LLVM project. "Apple X.Y" refers to an +Apple-provided release of the Apple LLVM Compiler. Other organizations that +prepare their own, separately-versioned clang releases and wish to maintain +similar information in this document should send requests to cfe-dev. + +If a change decreases the expressiveness of the language, for example by +imposing a new restriction, this should be taken as an oversight in the +original specification and something to be avoided in all versions. Such +changes are generally to be avoided. + +.. _arc.general: + +General +======= + +Automatic Reference Counting implements automatic memory management for +Objective-C objects and blocks, freeing the programmer from the need to +explicitly insert retains and releases. It does not provide a cycle collector; +users must explicitly manage the lifetime of their objects, breaking cycles +manually or with weak or unsafe references. + +ARC may be explicitly enabled with the compiler flag ``-fobjc-arc``. It may +also be explicitly disabled with the compiler flag ``-fno-objc-arc``. The last +of these two flags appearing on the compile line "wins". + +If ARC is enabled, ``__has_feature(objc_arc)`` will expand to 1 in the +preprocessor. For more information about ``__has_feature``, see the +:ref:`language extensions ` document. + +.. _arc.objects: + +Retainable object pointers +========================== + +This section describes retainable object pointers, their basic operations, and +the restrictions imposed on their use under ARC. Note in particular that it +covers the rules for pointer *values* (patterns of bits indicating the location +of a pointed-to object), not pointer *objects* (locations in memory which store +pointer values). The rules for objects are covered in the next section. + +A :arc-term:`retainable object pointer` (or "retainable pointer") is a value of +a :arc-term:`retainable object pointer type` ("retainable type"). There are +three kinds of retainable object pointer types: + +* block pointers (formed by applying the caret (``^``) declarator sigil to a + function type) +* Objective-C object pointers (``id``, ``Class``, ``NSFoo*``, etc.) +* typedefs marked with ``__attribute__((NSObject))`` + +Other pointer types, such as ``int*`` and ``CFStringRef``, are not subject to +ARC's semantics and restrictions. + +.. admonition:: Rationale + + We are not at liberty to require all code to be recompiled with ARC; + therefore, ARC must interoperate with Objective-C code which manages retains + and releases manually. In general, there are three requirements in order for + a compiler-supported reference-count system to provide reliable + interoperation: + + * The type system must reliably identify which objects are to be managed. An + ``int*`` might be a pointer to a ``malloc``'ed array, or it might be an + interior pointer to such an array, or it might point to some field or local + variable. In contrast, values of the retainable object pointer types are + never interior. + + * The type system must reliably indicate how to manage objects of a type. + This usually means that the type must imply a procedure for incrementing + and decrementing retain counts. Supporting single-ownership objects + requires a lot more explicit mediation in the language. + + * There must be reliable conventions for whether and when "ownership" is + passed between caller and callee, for both arguments and return values. + Objective-C methods follow such a convention very reliably, at least for + system libraries on Mac OS X, and functions always pass objects at +0. The + C-based APIs for Core Foundation objects, on the other hand, have much more + varied transfer semantics. + +The use of ``__attribute__((NSObject))`` typedefs is not recommended. If it's +absolutely necessary to use this attribute, be very explicit about using the +typedef, and do not assume that it will be preserved by language features like +``__typeof`` and C++ template argument substitution. + +.. admonition:: Rationale + + Any compiler operation which incidentally strips type "sugar" from a type + will yield a type without the attribute, which may result in unexpected + behavior. + +.. _arc.objects.retains: + +Retain count semantics +---------------------- + +A retainable object pointer is either a :arc-term:`null pointer` or a pointer +to a valid object. Furthermore, if it has block pointer type and is not +``null`` then it must actually be a pointer to a block object, and if it has +``Class`` type (possibly protocol-qualified) then it must actually be a pointer +to a class object. Otherwise ARC does not enforce the Objective-C type system +as long as the implementing methods follow the signature of the static type. +It is undefined behavior if ARC is exposed to an invalid pointer. + +For ARC's purposes, a valid object is one with "well-behaved" retaining +operations. Specifically, the object must be laid out such that the +Objective-C message send machinery can successfully send it the following +messages: + +* ``retain``, taking no arguments and returning a pointer to the object. +* ``release``, taking no arguments and returning ``void``. +* ``autorelease``, taking no arguments and returning a pointer to the object. + +The behavior of these methods is constrained in the following ways. The term +:arc-term:`high-level semantics` is an intentionally vague term; the intent is +that programmers must implement these methods in a way such that the compiler, +modifying code in ways it deems safe according to these constraints, will not +violate their requirements. For example, if the user puts logging statements +in ``retain``, they should not be surprised if those statements are executed +more or less often depending on optimization settings. These constraints are +not exhaustive of the optimization opportunities: values held in local +variables are subject to additional restrictions, described later in this +document. + +It is undefined behavior if a computation history featuring a send of +``retain`` followed by a send of ``release`` to the same object, with no +intervening ``release`` on that object, is not equivalent under the high-level +semantics to a computation history in which these sends are removed. Note that +this implies that these methods may not raise exceptions. + +It is undefined behavior if a computation history features any use whatsoever +of an object following the completion of a send of ``release`` that is not +preceded by a send of ``retain`` to the same object. + +The behavior of ``autorelease`` must be equivalent to sending ``release`` when +one of the autorelease pools currently in scope is popped. It may not throw an +exception. + +When the semantics call for performing one of these operations on a retainable +object pointer, if that pointer is ``null`` then the effect is a no-op. + +All of the semantics described in this document are subject to additional +:ref:`optimization rules ` which permit the removal or +optimization of operations based on local knowledge of data flow. The +semantics describe the high-level behaviors that the compiler implements, not +an exact sequence of operations that a program will be compiled into. + +.. _arc.objects.operands: + +Retainable object pointers as operands and arguments +---------------------------------------------------- + +In general, ARC does not perform retain or release operations when simply using +a retainable object pointer as an operand within an expression. This includes: + +* loading a retainable pointer from an object with non-weak :ref:`ownership + `, +* passing a retainable pointer as an argument to a function or method, and +* receiving a retainable pointer as the result of a function or method call. + +.. admonition:: Rationale + + While this might seem uncontroversial, it is actually unsafe when multiple + expressions are evaluated in "parallel", as with binary operators and calls, + because (for example) one expression might load from an object while another + writes to it. However, C and C++ already call this undefined behavior + because the evaluations are unsequenced, and ARC simply exploits that here to + avoid needing to retain arguments across a large number of calls. + +The remainder of this section describes exceptions to these rules, how those +exceptions are detected, and what those exceptions imply semantically. + +.. _arc.objects.operands.consumed: + +Consumed parameters +^^^^^^^^^^^^^^^^^^^ + +A function or method parameter of retainable object pointer type may be marked +as :arc-term:`consumed`, signifying that the callee expects to take ownership +of a +1 retain count. This is done by adding the ``ns_consumed`` attribute to +the parameter declaration, like so: + +.. code-block:: objc + + void foo(__attribute((ns_consumed)) id x); + - (void) foo: (id) __attribute((ns_consumed)) x; + +This attribute is part of the type of the function or method, not the type of +the parameter. It controls only how the argument is passed and received. + +When passing such an argument, ARC retains the argument prior to making the +call. + +When receiving such an argument, ARC releases the argument at the end of the +function, subject to the usual optimizations for local values. + +.. admonition:: Rationale + + This formalizes direct transfers of ownership from a caller to a callee. The + most common scenario here is passing the ``self`` parameter to ``init``, but + it is useful to generalize. Typically, local optimization will remove any + extra retains and releases: on the caller side the retain will be merged with + a +1 source, and on the callee side the release will be rolled into the + initialization of the parameter. + +The implicit ``self`` parameter of a method may be marked as consumed by adding +``__attribute__((ns_consumes_self))`` to the method declaration. Methods in +the ``init`` :ref:`family ` are treated as if they were +implicitly marked with this attribute. + +It is undefined behavior if an Objective-C message send to a method with +``ns_consumed`` parameters (other than self) is made with a null receiver. It +is undefined behavior if the method to which an Objective-C message send +statically resolves to has a different set of ``ns_consumed`` parameters than +the method it dynamically resolves to. It is undefined behavior if a block or +function call is made through a static type with a different set of +``ns_consumed`` parameters than the implementation of the called block or +function. + +.. admonition:: Rationale + + Consumed parameters with null receiver are a guaranteed leak. Mismatches + with consumed parameters will cause over-retains or over-releases, depending + on the direction. The rule about function calls is really just an + application of the existing C/C++ rule about calling functions through an + incompatible function type, but it's useful to state it explicitly. + +.. _arc.object.operands.retained-return-values: + +Retained return values +^^^^^^^^^^^^^^^^^^^^^^ + +A function or method which returns a retainable object pointer type may be +marked as returning a retained value, signifying that the caller expects to take +ownership of a +1 retain count. This is done by adding the +``ns_returns_retained`` attribute to the function or method declaration, like +so: + +.. code-block:: objc + + id foo(void) __attribute((ns_returns_retained)); + - (id) foo __attribute((ns_returns_retained)); + +This attribute is part of the type of the function or method. + +When returning from such a function or method, ARC retains the value at the +point of evaluation of the return statement, before leaving all local scopes. + +When receiving a return result from such a function or method, ARC releases the +value at the end of the full-expression it is contained within, subject to the +usual optimizations for local values. + +.. admonition:: Rationale + + This formalizes direct transfers of ownership from a callee to a caller. The + most common scenario this models is the retained return from ``init``, + ``alloc``, ``new``, and ``copy`` methods, but there are other cases in the + frameworks. After optimization there are typically no extra retains and + releases required. + +Methods in the ``alloc``, ``copy``, ``init``, ``mutableCopy``, and ``new`` +:ref:`families ` are implicitly marked +``__attribute__((ns_returns_retained))``. This may be suppressed by explicitly +marking the method ``__attribute__((ns_returns_not_retained))``. + +It is undefined behavior if the method to which an Objective-C message send +statically resolves has different retain semantics on its result from the +method it dynamically resolves to. It is undefined behavior if a block or +function call is made through a static type with different retain semantics on +its result from the implementation of the called block or function. + +.. admonition:: Rationale + + Mismatches with returned results will cause over-retains or over-releases, + depending on the direction. Again, the rule about function calls is really + just an application of the existing C/C++ rule about calling functions + through an incompatible function type. + +.. _arc.objects.operands.unretained-returns: + +Unretained return values +^^^^^^^^^^^^^^^^^^^^^^^^ + +A method or function which returns a retainable object type but does not return +a retained value must ensure that the object is still valid across the return +boundary. + +When returning from such a function or method, ARC retains the value at the +point of evaluation of the return statement, then leaves all local scopes, and +then balances out the retain while ensuring that the value lives across the +call boundary. In the worst case, this may involve an ``autorelease``, but +callers must not assume that the value is actually in the autorelease pool. + +ARC performs no extra mandatory work on the caller side, although it may elect +to do something to shorten the lifetime of the returned value. + +.. admonition:: Rationale + + It is common in non-ARC code to not return an autoreleased value; therefore + the convention does not force either path. It is convenient to not be + required to do unnecessary retains and autoreleases; this permits + optimizations such as eliding retain/autoreleases when it can be shown that + the original pointer will still be valid at the point of return. + +A method or function may be marked with +``__attribute__((ns_returns_autoreleased))`` to indicate that it returns a +pointer which is guaranteed to be valid at least as long as the innermost +autorelease pool. There are no additional semantics enforced in the definition +of such a method; it merely enables optimizations in callers. + +.. _arc.objects.operands.casts: + +Bridged casts +^^^^^^^^^^^^^ + +A :arc-term:`bridged cast` is a C-style cast annotated with one of three +keywords: + +* ``(__bridge T) op`` casts the operand to the destination type ``T``. If + ``T`` is a retainable object pointer type, then ``op`` must have a + non-retainable pointer type. If ``T`` is a non-retainable pointer type, + then ``op`` must have a retainable object pointer type. Otherwise the cast + is ill-formed. There is no transfer of ownership, and ARC inserts no retain + operations. +* ``(__bridge_retained T) op`` casts the operand, which must have retainable + object pointer type, to the destination type, which must be a non-retainable + pointer type. ARC retains the value, subject to the usual optimizations on + local values, and the recipient is responsible for balancing that +1. +* ``(__bridge_transfer T) op`` casts the operand, which must have + non-retainable pointer type, to the destination type, which must be a + retainable object pointer type. ARC will release the value at the end of + the enclosing full-expression, subject to the usual optimizations on local + values. + +These casts are required in order to transfer objects in and out of ARC +control; see the rationale in the section on :ref:`conversion of retainable +object pointers `. + +Using a ``__bridge_retained`` or ``__bridge_transfer`` cast purely to convince +ARC to emit an unbalanced retain or release, respectively, is poor form. + +.. _arc.objects.restrictions: + +Restrictions +------------ + +.. _arc.objects.restrictions.conversion: + +Conversion of retainable object pointers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In general, a program which attempts to implicitly or explicitly convert a +value of retainable object pointer type to any non-retainable type, or +vice-versa, is ill-formed. For example, an Objective-C object pointer shall +not be converted to ``void*``. As an exception, cast to ``intptr_t`` is +allowed because such casts are not transferring ownership. The :ref:`bridged +casts ` may be used to perform these conversions +where necessary. + +.. admonition:: Rationale + + We cannot ensure the correct management of the lifetime of objects if they + may be freely passed around as unmanaged types. The bridged casts are + provided so that the programmer may explicitly describe whether the cast + transfers control into or out of ARC. + +However, the following exceptions apply. + +.. _arc.objects.restrictions.conversion.with.known.semantics: + +Conversion to retainable object pointer type of expressions with known semantics +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:when-revised:`[beginning Apple 4.0, LLVM 3.1]` +:revision:`These exceptions have been greatly expanded; they previously applied +only to a much-reduced subset which is difficult to categorize but which +included null pointers, message sends (under the given rules), and the various +global constants.` + +An unbridged conversion to a retainable object pointer type from a type other +than a retainable object pointer type is ill-formed, as discussed above, unless +the operand of the cast has a syntactic form which is known retained, known +unretained, or known retain-agnostic. + +An expression is :arc-term:`known retain-agnostic` if it is: + +* an Objective-C string literal, +* a load from a ``const`` system global variable of :ref:`C retainable pointer + type `, or +* a null pointer constant. + +An expression is :arc-term:`known unretained` if it is an rvalue of :ref:`C +retainable pointer type ` and it is: + +* a direct call to a function, and either that function has the + ``cf_returns_not_retained`` attribute or it is an :ref:`audited + ` function that does not have the + ``cf_returns_retained`` attribute and does not follow the create/copy naming + convention, +* a message send, and the declared method either has the + ``cf_returns_not_retained`` attribute or it has neither the + ``cf_returns_retained`` attribute nor a :ref:`selector family + ` that implies a retained result. + +An expression is :arc-term:`known retained` if it is an rvalue of :ref:`C +retainable pointer type ` and it is: + +* a message send, and the declared method either has the + ``cf_returns_retained`` attribute, or it does not have the + ``cf_returns_not_retained`` attribute but it does have a :ref:`selector + family ` that implies a retained result. + +Furthermore: + +* a comma expression is classified according to its right-hand side, +* a statement expression is classified according to its result expression, if + it has one, +* an lvalue-to-rvalue conversion applied to an Objective-C property lvalue is + classified according to the underlying message send, and +* a conditional operator is classified according to its second and third + operands, if they agree in classification, or else the other if one is known + retain-agnostic. + +If the cast operand is known retained, the conversion is treated as a +``__bridge_transfer`` cast. If the cast operand is known unretained or known +retain-agnostic, the conversion is treated as a ``__bridge`` cast. + +.. admonition:: Rationale + + Bridging casts are annoying. Absent the ability to completely automate the + management of CF objects, however, we are left with relatively poor attempts + to reduce the need for a glut of explicit bridges. Hence these rules. + + We've so far consciously refrained from implicitly turning retained CF + results from function calls into ``__bridge_transfer`` casts. The worry is + that some code patterns --- for example, creating a CF value, assigning it + to an ObjC-typed local, and then calling ``CFRelease`` when done --- are a + bit too likely to be accidentally accepted, leading to mysterious behavior. + +.. _arc.objects.restrictions.conversion-exception-contextual: + +Conversion from retainable object pointer type in certain contexts +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:when-revised:`[beginning Apple 4.0, LLVM 3.1]` + +If an expression of retainable object pointer type is explicitly cast to a +:ref:`C retainable pointer type `, the program is +ill-formed as discussed above unless the result is immediately used: + +* to initialize a parameter in an Objective-C message send where the parameter + is not marked with the ``cf_consumed`` attribute, or +* to initialize a parameter in a direct call to an + :ref:`audited ` function where the parameter is + not marked with the ``cf_consumed`` attribute. + +.. admonition:: Rationale + + Consumed parameters are left out because ARC would naturally balance them + with a retain, which was judged too treacherous. This is in part because + several of the most common consuming functions are in the ``Release`` family, + and it would be quite unfortunate for explicit releases to be silently + balanced out in this way. + +.. _arc.ownership: + +Ownership qualification +======================= + +This section describes the behavior of *objects* of retainable object pointer +type; that is, locations in memory which store retainable object pointers. + +A type is a :arc-term:`retainable object owner type` if it is a retainable +object pointer type or an array type whose element type is a retainable object +owner type. + +An :arc-term:`ownership qualifier` is a type qualifier which applies only to +retainable object owner types. An array type is ownership-qualified according +to its element type, and adding an ownership qualifier to an array type so +qualifies its element type. + +A program is ill-formed if it attempts to apply an ownership qualifier to a +type which is already ownership-qualified, even if it is the same qualifier. +There is a single exception to this rule: an ownership qualifier may be applied +to a substituted template type parameter, which overrides the ownership +qualifier provided by the template argument. + +When forming a function type, the result type is adjusted so that any +top-level ownership qualifier is deleted. + +Except as described under the :ref:`inference rules `, +a program is ill-formed if it attempts to form a pointer or reference type to a +retainable object owner type which lacks an ownership qualifier. + +.. admonition:: Rationale + + These rules, together with the inference rules, ensure that all objects and + lvalues of retainable object pointer type have an ownership qualifier. The + ability to override an ownership qualifier during template substitution is + required to counteract the :ref:`inference of __strong for template type + arguments `. Ownership qualifiers + on return types are dropped because they serve no purpose there except to + cause spurious problems with overloading and templates. + +There are four ownership qualifiers: + +* ``__autoreleasing`` +* ``__strong`` +* ``__unsafe_unretained`` +* ``__weak`` + +A type is :arc-term:`nontrivially ownership-qualified` if it is qualified with +``__autoreleasing``, ``__strong``, or ``__weak``. + +.. _arc.ownership.spelling: + +Spelling +-------- + +The names of the ownership qualifiers are reserved for the implementation. A +program may not assume that they are or are not implemented with macros, or +what those macros expand to. + +An ownership qualifier may be written anywhere that any other type qualifier +may be written. + +If an ownership qualifier appears in the *declaration-specifiers*, the +following rules apply: + +* if the type specifier is a retainable object owner type, the qualifier + initially applies to that type; + +* otherwise, if the outermost non-array declarator is a pointer + or block pointer declarator, the qualifier initially applies to + that type; + +* otherwise the program is ill-formed. + +* If the qualifier is so applied at a position in the declaration + where the next-innermost declarator is a function declarator, and + there is an block declarator within that function declarator, then + the qualifier applies instead to that block declarator and this rule + is considered afresh beginning from the new position. + +If an ownership qualifier appears on the declarator name, or on the declared +object, it is applied to the innermost pointer or block-pointer type. + +If an ownership qualifier appears anywhere else in a declarator, it applies to +the type there. + +.. admonition:: Rationale + + Ownership qualifiers are like ``const`` and ``volatile`` in the sense + that they may sensibly apply at multiple distinct positions within a + declarator. However, unlike those qualifiers, there are many + situations where they are not meaningful, and so we make an effort + to "move" the qualifier to a place where it will be meaningful. The + general goal is to allow the programmer to write, say, ``__strong`` + before the entire declaration and have it apply in the leftmost + sensible place. + +.. _arc.ownership.spelling.property: + +Property declarations +^^^^^^^^^^^^^^^^^^^^^ + +A property of retainable object pointer type may have ownership. If the +property's type is ownership-qualified, then the property has that ownership. +If the property has one of the following modifiers, then the property has the +corresponding ownership. A property is ill-formed if it has conflicting +sources of ownership, or if it has redundant ownership modifiers, or if it has +``__autoreleasing`` ownership. + +* ``assign`` implies ``__unsafe_unretained`` ownership. +* ``copy`` implies ``__strong`` ownership, as well as the usual behavior of + copy semantics on the setter. +* ``retain`` implies ``__strong`` ownership. +* ``strong`` implies ``__strong`` ownership. +* ``unsafe_unretained`` implies ``__unsafe_unretained`` ownership. +* ``weak`` implies ``__weak`` ownership. + +With the exception of ``weak``, these modifiers are available in non-ARC +modes. + +A property's specified ownership is preserved in its metadata, but otherwise +the meaning is purely conventional unless the property is synthesized. If a +property is synthesized, then the :arc-term:`associated instance variable` is +the instance variable which is named, possibly implicitly, by the +``@synthesize`` declaration. If the associated instance variable already +exists, then its ownership qualification must equal the ownership of the +property; otherwise, the instance variable is created with that ownership +qualification. + +A property of retainable object pointer type which is synthesized without a +source of ownership has the ownership of its associated instance variable, if it +already exists; otherwise, :when-revised:`[beginning Apple 3.1, LLVM 3.1]` +:revision:`its ownership is implicitly` ``strong``. Prior to this revision, it +was ill-formed to synthesize such a property. + +.. admonition:: Rationale + + Using ``strong`` by default is safe and consistent with the generic ARC rule + about :ref:`inferring ownership `. It is, + unfortunately, inconsistent with the non-ARC rule which states that such + properties are implicitly ``assign``. However, that rule is clearly + untenable in ARC, since it leads to default-unsafe code. The main merit to + banning the properties is to avoid confusion with non-ARC practice, which did + not ultimately strike us as sufficient to justify requiring extra syntax and + (more importantly) forcing novices to understand ownership rules just to + declare a property when the default is so reasonable. Changing the rule away + from non-ARC practice was acceptable because we had conservatively banned the + synthesis in order to give ourselves exactly this leeway. + +Applying ``__attribute__((NSObject))`` to a property not of retainable object +pointer type has the same behavior it does outside of ARC: it requires the +property type to be some sort of pointer and permits the use of modifiers other +than ``assign``. These modifiers only affect the synthesized getter and +setter; direct accesses to the ivar (even if synthesized) still have primitive +semantics, and the value in the ivar will not be automatically released during +deallocation. + +.. _arc.ownership.semantics: + +Semantics +--------- + +There are five :arc-term:`managed operations` which may be performed on an +object of retainable object pointer type. Each qualifier specifies different +semantics for each of these operations. It is still undefined behavior to +access an object outside of its lifetime. + +A load or store with "primitive semantics" has the same semantics as the +respective operation would have on an ``void*`` lvalue with the same alignment +and non-ownership qualification. + +:arc-term:`Reading` occurs when performing a lvalue-to-rvalue conversion on an +object lvalue. + +* For ``__weak`` objects, the current pointee is retained and then released at + the end of the current full-expression. This must execute atomically with + respect to assignments and to the final release of the pointee. +* For all other objects, the lvalue is loaded with primitive semantics. + +:arc-term:`Assignment` occurs when evaluating an assignment operator. The +semantics vary based on the qualification: + +* For ``__strong`` objects, the new pointee is first retained; second, the + lvalue is loaded with primitive semantics; third, the new pointee is stored + into the lvalue with primitive semantics; and finally, the old pointee is + released. This is not performed atomically; external synchronization must be + used to make this safe in the face of concurrent loads and stores. +* For ``__weak`` objects, the lvalue is updated to point to the new pointee, + unless the new pointee is an object currently undergoing deallocation, in + which case the lvalue is updated to a null pointer. This must execute + atomically with respect to other assignments to the object, to reads from the + object, and to the final release of the new pointee. +* For ``__unsafe_unretained`` objects, the new pointee is stored into the + lvalue using primitive semantics. +* For ``__autoreleasing`` objects, the new pointee is retained, autoreleased, + and stored into the lvalue using primitive semantics. + +:arc-term:`Initialization` occurs when an object's lifetime begins, which +depends on its storage duration. Initialization proceeds in two stages: + +#. First, a null pointer is stored into the lvalue using primitive semantics. + This step is skipped if the object is ``__unsafe_unretained``. +#. Second, if the object has an initializer, that expression is evaluated and + then assigned into the object using the usual assignment semantics. + +:arc-term:`Destruction` occurs when an object's lifetime ends. In all cases it +is semantically equivalent to assigning a null pointer to the object, with the +proviso that of course the object cannot be legally read after the object's +lifetime ends. + +:arc-term:`Moving` occurs in specific situations where an lvalue is "moved +from", meaning that its current pointee will be used but the object may be left +in a different (but still valid) state. This arises with ``__block`` variables +and rvalue references in C++. For ``__strong`` lvalues, moving is equivalent +to loading the lvalue with primitive semantics, writing a null pointer to it +with primitive semantics, and then releasing the result of the load at the end +of the current full-expression. For all other lvalues, moving is equivalent to +reading the object. + +.. _arc.ownership.restrictions: + +Restrictions +------------ + +.. _arc.ownership.restrictions.weak: + +Weak-unavailable types +^^^^^^^^^^^^^^^^^^^^^^ + +It is explicitly permitted for Objective-C classes to not support ``__weak`` +references. It is undefined behavior to perform an operation with weak +assignment semantics with a pointer to an Objective-C object whose class does +not support ``__weak`` references. + +.. admonition:: Rationale + + Historically, it has been possible for a class to provide its own + reference-count implementation by overriding ``retain``, ``release``, etc. + However, weak references to an object require coordination with its class's + reference-count implementation because, among other things, weak loads and + stores must be atomic with respect to the final release. Therefore, existing + custom reference-count implementations will generally not support weak + references without additional effort. This is unavoidable without breaking + binary compatibility. + +A class may indicate that it does not support weak references by providing the +``objc_arc_weak_unavailable`` attribute on the class's interface declaration. A +retainable object pointer type is **weak-unavailable** if +is a pointer to an (optionally protocol-qualified) Objective-C class ``T`` where +``T`` or one of its superclasses has the ``objc_arc_weak_unavailable`` +attribute. A program is ill-formed if it applies the ``__weak`` ownership +qualifier to a weak-unavailable type or if the value operand of a weak +assignment operation has a weak-unavailable type. + +.. _arc.ownership.restrictions.autoreleasing: + +Storage duration of ``__autoreleasing`` objects +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A program is ill-formed if it declares an ``__autoreleasing`` object of +non-automatic storage duration. A program is ill-formed if it captures an +``__autoreleasing`` object in a block or, unless by reference, in a C++11 +lambda. + +.. admonition:: Rationale + + Autorelease pools are tied to the current thread and scope by their nature. + While it is possible to have temporary objects whose instance variables are + filled with autoreleased objects, there is no way that ARC can provide any + sort of safety guarantee there. + +It is undefined behavior if a non-null pointer is assigned to an +``__autoreleasing`` object while an autorelease pool is in scope and then that +object is read after the autorelease pool's scope is left. + +.. _arc.ownership.restrictions.conversion.indirect: + +Conversion of pointers to ownership-qualified types +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A program is ill-formed if an expression of type ``T*`` is converted, +explicitly or implicitly, to the type ``U*``, where ``T`` and ``U`` have +different ownership qualification, unless: + +* ``T`` is qualified with ``__strong``, ``__autoreleasing``, or + ``__unsafe_unretained``, and ``U`` is qualified with both ``const`` and + ``__unsafe_unretained``; or +* either ``T`` or ``U`` is ``cv void``, where ``cv`` is an optional sequence + of non-ownership qualifiers; or +* the conversion is requested with a ``reinterpret_cast`` in Objective-C++; or +* the conversion is a well-formed :ref:`pass-by-writeback + `. + +The analogous rule applies to ``T&`` and ``U&`` in Objective-C++. + +.. admonition:: Rationale + + These rules provide a reasonable level of type-safety for indirect pointers, + as long as the underlying memory is not deallocated. The conversion to + ``const __unsafe_unretained`` is permitted because the semantics of reads are + equivalent across all these ownership semantics, and that's a very useful and + common pattern. The interconversion with ``void*`` is useful for allocating + memory or otherwise escaping the type system, but use it carefully. + ``reinterpret_cast`` is considered to be an obvious enough sign of taking + responsibility for any problems. + +It is undefined behavior to access an ownership-qualified object through an +lvalue of a differently-qualified type, except that any non-``__weak`` object +may be read through an ``__unsafe_unretained`` lvalue. + +It is undefined behavior if a managed operation is performed on a ``__strong`` +or ``__weak`` object without a guarantee that it contains a primitive zero +bit-pattern, or if the storage for such an object is freed or reused without the +object being first assigned a null pointer. + +.. admonition:: Rationale + + ARC cannot differentiate between an assignment operator which is intended to + "initialize" dynamic memory and one which is intended to potentially replace + a value. Therefore the object's pointer must be valid before letting ARC at + it. Similarly, C and Objective-C do not provide any language hooks for + destroying objects held in dynamic memory, so it is the programmer's + responsibility to avoid leaks (``__strong`` objects) and consistency errors + (``__weak`` objects). + +These requirements are followed automatically in Objective-C++ when creating +objects of retainable object owner type with ``new`` or ``new[]`` and destroying +them with ``delete``, ``delete[]``, or a pseudo-destructor expression. Note +that arrays of nontrivially-ownership-qualified type are not ABI compatible with +non-ARC code because the element type is non-POD: such arrays that are +``new[]``'d in ARC translation units cannot be ``delete[]``'d in non-ARC +translation units and vice-versa. + +.. _arc.ownership.restrictions.pass_by_writeback: + +Passing to an out parameter by writeback +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the argument passed to a parameter of type ``T __autoreleasing *`` has type +``U oq *``, where ``oq`` is an ownership qualifier, then the argument is a +candidate for :arc-term:`pass-by-writeback`` if: + +* ``oq`` is ``__strong`` or ``__weak``, and +* it would be legal to initialize a ``T __strong *`` with a ``U __strong *``. + +For purposes of overload resolution, an implicit conversion sequence requiring +a pass-by-writeback is always worse than an implicit conversion sequence not +requiring a pass-by-writeback. + +The pass-by-writeback is ill-formed if the argument expression does not have a +legal form: + +* ``&var``, where ``var`` is a scalar variable of automatic storage duration + with retainable object pointer type +* a conditional expression where the second and third operands are both legal + forms +* a cast whose operand is a legal form +* a null pointer constant + +.. admonition:: Rationale + + The restriction in the form of the argument serves two purposes. First, it + makes it impossible to pass the address of an array to the argument, which + serves to protect against an otherwise serious risk of mis-inferring an + "array" argument as an out-parameter. Second, it makes it much less likely + that the user will see confusing aliasing problems due to the implementation, + below, where their store to the writeback temporary is not immediately seen + in the original argument variable. + +A pass-by-writeback is evaluated as follows: + +#. The argument is evaluated to yield a pointer ``p`` of type ``U oq *``. +#. If ``p`` is a null pointer, then a null pointer is passed as the argument, + and no further work is required for the pass-by-writeback. +#. Otherwise, a temporary of type ``T __autoreleasing`` is created and + initialized to a null pointer. +#. If the parameter is not an Objective-C method parameter marked ``out``, + then ``*p`` is read, and the result is written into the temporary with + primitive semantics. +#. The address of the temporary is passed as the argument to the actual call. +#. After the call completes, the temporary is loaded with primitive + semantics, and that value is assigned into ``*p``. + +.. admonition:: Rationale + + This is all admittedly convoluted. In an ideal world, we would see that a + local variable is being passed to an out-parameter and retroactively modify + its type to be ``__autoreleasing`` rather than ``__strong``. This would be + remarkably difficult and not always well-founded under the C type system. + However, it was judged unacceptably invasive to require programmers to write + ``__autoreleasing`` on all the variables they intend to use for + out-parameters. This was the least bad solution. + +.. _arc.ownership.restrictions.records: + +Ownership-qualified fields of structs and unions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A program is ill-formed if it declares a member of a C struct or union to have +a nontrivially ownership-qualified type. + +.. admonition:: Rationale + + The resulting type would be non-POD in the C++ sense, but C does not give us + very good language tools for managing the lifetime of aggregates, so it is + more convenient to simply forbid them. It is still possible to manage this + with a ``void*`` or an ``__unsafe_unretained`` object. + +This restriction does not apply in Objective-C++. However, nontrivally +ownership-qualified types are considered non-POD: in C++11 terms, they are not +trivially default constructible, copy constructible, move constructible, copy +assignable, move assignable, or destructible. It is a violation of C++'s One +Definition Rule to use a class outside of ARC that, under ARC, would have a +nontrivially ownership-qualified member. + +.. admonition:: Rationale + + Unlike in C, we can express all the necessary ARC semantics for + ownership-qualified subobjects as suboperations of the (default) special + member functions for the class. These functions then become non-trivial. + This has the non-obvious result that the class will have a non-trivial copy + constructor and non-trivial destructor; if this would not normally be true + outside of ARC, objects of the type will be passed and returned in an + ABI-incompatible manner. + +.. _arc.ownership.inference: + +Ownership inference +------------------- + +.. _arc.ownership.inference.variables: + +Objects +^^^^^^^ + +If an object is declared with retainable object owner type, but without an +explicit ownership qualifier, its type is implicitly adjusted to have +``__strong`` qualification. + +As a special case, if the object's base type is ``Class`` (possibly +protocol-qualified), the type is adjusted to have ``__unsafe_unretained`` +qualification instead. + +.. _arc.ownership.inference.indirect_parameters: + +Indirect parameters +^^^^^^^^^^^^^^^^^^^ + +If a function or method parameter has type ``T*``, where ``T`` is an +ownership-unqualified retainable object pointer type, then: + +* if ``T`` is ``const``-qualified or ``Class``, then it is implicitly + qualified with ``__unsafe_unretained``; +* otherwise, it is implicitly qualified with ``__autoreleasing``. + +.. admonition:: Rationale + + ``__autoreleasing`` exists mostly for this case, the Cocoa convention for + out-parameters. Since a pointer to ``const`` is obviously not an + out-parameter, we instead use a type more useful for passing arrays. If the + user instead intends to pass in a *mutable* array, inferring + ``__autoreleasing`` is the wrong thing to do; this directs some of the + caution in the following rules about writeback. + +Such a type written anywhere else would be ill-formed by the general rule +requiring ownership qualifiers. + +This rule does not apply in Objective-C++ if a parameter's type is dependent in +a template pattern and is only *instantiated* to a type which would be a +pointer to an unqualified retainable object pointer type. Such code is still +ill-formed. + +.. admonition:: Rationale + + The convention is very unlikely to be intentional in template code. + +.. _arc.ownership.inference.template.arguments: + +Template arguments +^^^^^^^^^^^^^^^^^^ + +If a template argument for a template type parameter is an retainable object +owner type that does not have an explicit ownership qualifier, it is adjusted +to have ``__strong`` qualification. This adjustment occurs regardless of +whether the template argument was deduced or explicitly specified. + +.. admonition:: Rationale + + ``__strong`` is a useful default for containers (e.g., ``std::vector``), + which would otherwise require explicit qualification. Moreover, unqualified + retainable object pointer types are unlikely to be useful within templates, + since they generally need to have a qualifier applied to the before being + used. + +.. _arc.method-families: + +Method families +=============== + +An Objective-C method may fall into a :arc-term:`method family`, which is a +conventional set of behaviors ascribed to it by the Cocoa conventions. + +A method is in a certain method family if: + +* it has a ``objc_method_family`` attribute placing it in that family; or if + not that, +* it does not have an ``objc_method_family`` attribute placing it in a + different or no family, and +* its selector falls into the corresponding selector family, and +* its signature obeys the added restrictions of the method family. + +A selector is in a certain selector family if, ignoring any leading +underscores, the first component of the selector either consists entirely of +the name of the method family or it begins with that name followed by a +character other than a lowercase letter. For example, ``_perform:with:`` and +``performWith:`` would fall into the ``perform`` family (if we recognized one), +but ``performing:with`` would not. + +The families and their added restrictions are: + +* ``alloc`` methods must return a retainable object pointer type. +* ``copy`` methods must return a retainable object pointer type. +* ``mutableCopy`` methods must return a retainable object pointer type. +* ``new`` methods must return a retainable object pointer type. +* ``init`` methods must be instance methods and must return an Objective-C + pointer type. Additionally, a program is ill-formed if it declares or + contains a call to an ``init`` method whose return type is neither ``id`` nor + a pointer to a super-class or sub-class of the declaring class (if the method + was declared on a class) or the static receiver type of the call (if it was + declared on a protocol). + + .. admonition:: Rationale + + There are a fair number of existing methods with ``init``-like selectors + which nonetheless don't follow the ``init`` conventions. Typically these + are either accidental naming collisions or helper methods called during + initialization. Because of the peculiar retain/release behavior of + ``init`` methods, it's very important not to treat these methods as + ``init`` methods if they aren't meant to be. It was felt that implicitly + defining these methods out of the family based on the exact relationship + between the return type and the declaring class would be much too subtle + and fragile. Therefore we identify a small number of legitimate-seeming + return types and call everything else an error. This serves the secondary + purpose of encouraging programmers not to accidentally give methods names + in the ``init`` family. + + Note that a method with an ``init``-family selector which returns a + non-Objective-C type (e.g. ``void``) is perfectly well-formed; it simply + isn't in the ``init`` family. + +A program is ill-formed if a method's declarations, implementations, and +overrides do not all have the same method family. + +.. _arc.family.attribute: + +Explicit method family control +------------------------------ + +A method may be annotated with the ``objc_method_family`` attribute to +precisely control which method family it belongs to. If a method in an +``@implementation`` does not have this attribute, but there is a method +declared in the corresponding ``@interface`` that does, then the attribute is +copied to the declaration in the ``@implementation``. The attribute is +available outside of ARC, and may be tested for with the preprocessor query +``__has_attribute(objc_method_family)``. + +The attribute is spelled +``__attribute__((objc_method_family(`` *family* ``)))``. If *family* is +``none``, the method has no family, even if it would otherwise be considered to +have one based on its selector and type. Otherwise, *family* must be one of +``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``, in which case the +method is considered to belong to the corresponding family regardless of its +selector. It is an error if a method that is explicitly added to a family in +this way does not meet the requirements of the family other than the selector +naming convention. + +.. admonition:: Rationale + + The rules codified in this document describe the standard conventions of + Objective-C. However, as these conventions have not heretofore been enforced + by an unforgiving mechanical system, they are only imperfectly kept, + especially as they haven't always even been precisely defined. While it is + possible to define low-level ownership semantics with attributes like + ``ns_returns_retained``, this attribute allows the user to communicate + semantic intent, which is of use both to ARC (which, e.g., treats calls to + ``init`` specially) and the static analyzer. + +.. _arc.family.semantics: + +Semantics of method families +---------------------------- + +A method's membership in a method family may imply non-standard semantics for +its parameters and return type. + +Methods in the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families --- +that is, methods in all the currently-defined families except ``init`` --- +implicitly :ref:`return a retained object +` as if they were annotated with +the ``ns_returns_retained`` attribute. This can be overridden by annotating +the method with either of the ``ns_returns_autoreleased`` or +``ns_returns_not_retained`` attributes. + +Properties also follow same naming rules as methods. This means that those in +the ``alloc``, ``copy``, ``mutableCopy``, and ``new`` families provide access +to :ref:`retained objects `. This +can be overridden by annotating the property with ``ns_returns_not_retained`` +attribute. + +.. _arc.family.semantics.init: + +Semantics of ``init`` +^^^^^^^^^^^^^^^^^^^^^ + +Methods in the ``init`` family implicitly :ref:`consume +` their ``self`` parameter and :ref:`return a +retained object `. Neither of +these properties can be altered through attributes. + +A call to an ``init`` method with a receiver that is either ``self`` (possibly +parenthesized or casted) or ``super`` is called a :arc-term:`delegate init +call`. It is an error for a delegate init call to be made except from an +``init`` method, and excluding blocks within such methods. + +As an exception to the :ref:`usual rule `, the variable ``self`` +is mutable in an ``init`` method and has the usual semantics for a ``__strong`` +variable. However, it is undefined behavior and the program is ill-formed, no +diagnostic required, if an ``init`` method attempts to use the previous value +of ``self`` after the completion of a delegate init call. It is conventional, +but not required, for an ``init`` method to return ``self``. + +It is undefined behavior for a program to cause two or more calls to ``init`` +methods on the same object, except that each ``init`` method invocation may +perform at most one delegate init call. + +.. _arc.family.semantics.result_type: + +Related result types +^^^^^^^^^^^^^^^^^^^^ + +Certain methods are candidates to have :arc-term:`related result types`: + +* class methods in the ``alloc`` and ``new`` method families +* instance methods in the ``init`` family +* the instance method ``self`` +* outside of ARC, the instance methods ``retain`` and ``autorelease`` + +If the formal result type of such a method is ``id`` or protocol-qualified +``id``, or a type equal to the declaring class or a superclass, then it is said +to have a related result type. In this case, when invoked in an explicit +message send, it is assumed to return a type related to the type of the +receiver: + +* if it is a class method, and the receiver is a class name ``T``, the message + send expression has type ``T*``; otherwise +* if it is an instance method, and the receiver has type ``T``, the message + send expression has type ``T``; otherwise +* the message send expression has the normal result type of the method. + +This is a new rule of the Objective-C language and applies outside of ARC. + +.. admonition:: Rationale + + ARC's automatic code emission is more prone than most code to signature + errors, i.e. errors where a call was emitted against one method signature, + but the implementing method has an incompatible signature. Having more + precise type information helps drastically lower this risk, as well as + catching a number of latent bugs. + +.. _arc.optimization: + +Optimization +============ + +Within this section, the word :arc-term:`function` will be used to +refer to any structured unit of code, be it a C function, an +Objective-C method, or a block. + +This specification describes ARC as performing specific ``retain`` and +``release`` operations on retainable object pointers at specific +points during the execution of a program. These operations make up a +non-contiguous subsequence of the computation history of the program. +The portion of this sequence for a particular retainable object +pointer for which a specific function execution is directly +responsible is the :arc-term:`formal local retain history` of the +object pointer. The corresponding actual sequence executed is the +`dynamic local retain history`. + +However, under certain circumstances, ARC is permitted to re-order and +eliminate operations in a manner which may alter the overall +computation history beyond what is permitted by the general "as if" +rule of C/C++ and the :ref:`restrictions ` on +the implementation of ``retain`` and ``release``. + +.. admonition:: Rationale + + Specifically, ARC is sometimes permitted to optimize ``release`` + operations in ways which might cause an object to be deallocated + before it would otherwise be. Without this, it would be almost + impossible to eliminate any ``retain``/``release`` pairs. For + example, consider the following code: + + .. code-block:: objc + + id x = _ivar; + [x foo]; + + If we were not permitted in any event to shorten the lifetime of the + object in ``x``, then we would not be able to eliminate this retain + and release unless we could prove that the message send could not + modify ``_ivar`` (or deallocate ``self``). Since message sends are + opaque to the optimizer, this is not possible, and so ARC's hands + would be almost completely tied. + +ARC makes no guarantees about the execution of a computation history +which contains undefined behavior. In particular, ARC makes no +guarantees in the presence of race conditions. + +ARC may assume that any retainable object pointers it receives or +generates are instantaneously valid from that point until a point +which, by the concurrency model of the host language, happens-after +the generation of the pointer and happens-before a release of that +object (possibly via an aliasing pointer or indirectly due to +destruction of a different object). + +.. admonition:: Rationale + + There is very little point in trying to guarantee correctness in the + presence of race conditions. ARC does not have a stack-scanning + garbage collector, and guaranteeing the atomicity of every load and + store operation would be prohibitive and preclude a vast amount of + optimization. + +ARC may assume that non-ARC code engages in sensible balancing +behavior and does not rely on exact or minimum retain count values +except as guaranteed by ``__strong`` object invariants or +1 transfer +conventions. For example, if an object is provably double-retained +and double-released, ARC may eliminate the inner retain and release; +it does not need to guard against code which performs an unbalanced +release followed by a "balancing" retain. + +.. _arc.optimization.liveness: + +Object liveness +--------------- + +ARC may not allow a retainable object ``X`` to be deallocated at a +time ``T`` in a computation history if: + +* ``X`` is the value stored in a ``__strong`` object ``S`` with + :ref:`precise lifetime semantics `, or + +* ``X`` is the value stored in a ``__strong`` object ``S`` with + imprecise lifetime semantics and, at some point after ``T`` but + before the next store to ``S``, the computation history features a + load from ``S`` and in some way depends on the value loaded, or + +* ``X`` is a value described as being released at the end of the + current full-expression and, at some point after ``T`` but before + the end of the full-expression, the computation history depends + on that value. + +.. admonition:: Rationale + + The intent of the second rule is to say that objects held in normal + ``__strong`` local variables may be released as soon as the value in + the variable is no longer being used: either the variable stops + being used completely or a new value is stored in the variable. + + The intent of the third rule is to say that return values may be + released after they've been used. + +A computation history depends on a pointer value ``P`` if it: + +* performs a pointer comparison with ``P``, +* loads from ``P``, +* stores to ``P``, +* depends on a pointer value ``Q`` derived via pointer arithmetic + from ``P`` (including an instance-variable or field access), or +* depends on a pointer value ``Q`` loaded from ``P``. + +Dependency applies only to values derived directly or indirectly from +a particular expression result and does not occur merely because a +separate pointer value dynamically aliases ``P``. Furthermore, this +dependency is not carried by values that are stored to objects. + +.. admonition:: Rationale + + The restrictions on dependency are intended to make this analysis + feasible by an optimizer with only incomplete information about a + program. Essentially, dependence is carried to "obvious" uses of a + pointer. Merely passing a pointer argument to a function does not + itself cause dependence, but since generally the optimizer will not + be able to prove that the function doesn't depend on that parameter, + it will be forced to conservatively assume it does. + + Dependency propagates to values loaded from a pointer because those + values might be invalidated by deallocating the object. For + example, given the code ``__strong id x = p->ivar;``, ARC must not + move the release of ``p`` to between the load of ``p->ivar`` and the + retain of that value for storing into ``x``. + + Dependency does not propagate through stores of dependent pointer + values because doing so would allow dependency to outlive the + full-expression which produced the original value. For example, the + address of an instance variable could be written to some global + location and then freely accessed during the lifetime of the local, + or a function could return an inner pointer of an object and store + it to a local. These cases would be potentially impossible to + reason about and so would basically prevent any optimizations based + on imprecise lifetime. There are also uncommon enough to make it + reasonable to require the precise-lifetime annotation if someone + really wants to rely on them. + + Dependency does propagate through return values of pointer type. + The compelling source of need for this rule is a property accessor + which returns an un-autoreleased result; the calling function must + have the chance to operate on the value, e.g. to retain it, before + ARC releases the original pointer. Note again, however, that + dependence does not survive a store, so ARC does not guarantee the + continued validity of the return value past the end of the + full-expression. + +.. _arc.optimization.object_lifetime: + +No object lifetime extension +---------------------------- + +If, in the formal computation history of the program, an object ``X`` +has been deallocated by the time of an observable side-effect, then +ARC must cause ``X`` to be deallocated by no later than the occurrence +of that side-effect, except as influenced by the re-ordering of the +destruction of objects. + +.. admonition:: Rationale + + This rule is intended to prohibit ARC from observably extending the + lifetime of a retainable object, other than as specified in this + document. Together with the rule limiting the transformation of + releases, this rule requires ARC to eliminate retains and release + only in pairs. + + ARC's power to reorder the destruction of objects is critical to its + ability to do any optimization, for essentially the same reason that + it must retain the power to decrease the lifetime of an object. + Unfortunately, while it's generally poor style for the destruction + of objects to have arbitrary side-effects, it's certainly possible. + Hence the caveat. + +.. _arc.optimization.precise: + +Precise lifetime semantics +-------------------------- + +In general, ARC maintains an invariant that a retainable object pointer held in +a ``__strong`` object will be retained for the full formal lifetime of the +object. Objects subject to this invariant have :arc-term:`precise lifetime +semantics`. + +By default, local variables of automatic storage duration do not have precise +lifetime semantics. Such objects are simply strong references which hold +values of retainable object pointer type, and these values are still fully +subject to the optimizations on values under local control. + +.. admonition:: Rationale + + Applying these precise-lifetime semantics strictly would be prohibitive. + Many useful optimizations that might theoretically decrease the lifetime of + an object would be rendered impossible. Essentially, it promises too much. + +A local variable of retainable object owner type and automatic storage duration +may be annotated with the ``objc_precise_lifetime`` attribute to indicate that +it should be considered to be an object with precise lifetime semantics. + +.. admonition:: Rationale + + Nonetheless, it is sometimes useful to be able to force an object to be + released at a precise time, even if that object does not appear to be used. + This is likely to be uncommon enough that the syntactic weight of explicitly + requesting these semantics will not be burdensome, and may even make the code + clearer. + +.. _arc.misc: + +Miscellaneous +============= + +.. _arc.misc.special_methods: + +Special methods +--------------- + +.. _arc.misc.special_methods.retain: + +Memory management methods +^^^^^^^^^^^^^^^^^^^^^^^^^ + +A program is ill-formed if it contains a method definition, message send, or +``@selector`` expression for any of the following selectors: + +* ``autorelease`` +* ``release`` +* ``retain`` +* ``retainCount`` + +.. admonition:: Rationale + + ``retainCount`` is banned because ARC robs it of consistent semantics. The + others were banned after weighing three options for how to deal with message + sends: + + **Honoring** them would work out very poorly if a programmer naively or + accidentally tried to incorporate code written for manual retain/release code + into an ARC program. At best, such code would do twice as much work as + necessary; quite frequently, however, ARC and the explicit code would both + try to balance the same retain, leading to crashes. The cost is losing the + ability to perform "unrooted" retains, i.e. retains not logically + corresponding to a strong reference in the object graph. + + **Ignoring** them would badly violate user expectations about their code. + While it *would* make it easier to develop code simultaneously for ARC and + non-ARC, there is very little reason to do so except for certain library + developers. ARC and non-ARC translation units share an execution model and + can seamlessly interoperate. Within a translation unit, a developer who + faithfully maintains their code in non-ARC mode is suffering all the + restrictions of ARC for zero benefit, while a developer who isn't testing the + non-ARC mode is likely to be unpleasantly surprised if they try to go back to + it. + + **Banning** them has the disadvantage of making it very awkward to migrate + existing code to ARC. The best answer to that, given a number of other + changes and restrictions in ARC, is to provide a specialized tool to assist + users in that migration. + + Implementing these methods was banned because they are too integral to the + semantics of ARC; many tricks which worked tolerably under manual reference + counting will misbehave if ARC performs an ephemeral extra retain or two. If + absolutely required, it is still possible to implement them in non-ARC code, + for example in a category; the implementations must obey the :ref:`semantics + ` laid out elsewhere in this document. + +.. _arc.misc.special_methods.dealloc: + +``dealloc`` +^^^^^^^^^^^ + +A program is ill-formed if it contains a message send or ``@selector`` +expression for the selector ``dealloc``. + +.. admonition:: Rationale + + There are no legitimate reasons to call ``dealloc`` directly. + +A class may provide a method definition for an instance method named +``dealloc``. This method will be called after the final ``release`` of the +object but before it is deallocated or any of its instance variables are +destroyed. The superclass's implementation of ``dealloc`` will be called +automatically when the method returns. + +.. admonition:: Rationale + + Even though ARC destroys instance variables automatically, there are still + legitimate reasons to write a ``dealloc`` method, such as freeing + non-retainable resources. Failing to call ``[super dealloc]`` in such a + method is nearly always a bug. Sometimes, the object is simply trying to + prevent itself from being destroyed, but ``dealloc`` is really far too late + for the object to be raising such objections. Somewhat more legitimately, an + object may have been pool-allocated and should not be deallocated with + ``free``; for now, this can only be supported with a ``dealloc`` + implementation outside of ARC. Such an implementation must be very careful + to do all the other work that ``NSObject``'s ``dealloc`` would, which is + outside the scope of this document to describe. + +The instance variables for an ARC-compiled class will be destroyed at some +point after control enters the ``dealloc`` method for the root class of the +class. The ordering of the destruction of instance variables is unspecified, +both within a single class and between subclasses and superclasses. + +.. admonition:: Rationale + + The traditional, non-ARC pattern for destroying instance variables is to + destroy them immediately before calling ``[super dealloc]``. Unfortunately, + message sends from the superclass are quite capable of reaching methods in + the subclass, and those methods may well read or write to those instance + variables. Making such message sends from dealloc is generally discouraged, + since the subclass may well rely on other invariants that were broken during + ``dealloc``, but it's not so inescapably dangerous that we felt comfortable + calling it undefined behavior. Therefore we chose to delay destroying the + instance variables to a point at which message sends are clearly disallowed: + the point at which the root class's deallocation routines take over. + + In most code, the difference is not observable. It can, however, be observed + if an instance variable holds a strong reference to an object whose + deallocation will trigger a side-effect which must be carefully ordered with + respect to the destruction of the super class. Such code violates the design + principle that semantically important behavior should be explicit. A simple + fix is to clear the instance variable manually during ``dealloc``; a more + holistic solution is to move semantically important side-effects out of + ``dealloc`` and into a separate teardown phase which can rely on working with + well-formed objects. + +.. _arc.misc.autoreleasepool: + +``@autoreleasepool`` +-------------------- + +To simplify the use of autorelease pools, and to bring them under the control +of the compiler, a new kind of statement is available in Objective-C. It is +written ``@autoreleasepool`` followed by a *compound-statement*, i.e. by a new +scope delimited by curly braces. Upon entry to this block, the current state +of the autorelease pool is captured. When the block is exited normally, +whether by fallthrough or directed control flow (such as ``return`` or +``break``), the autorelease pool is restored to the saved state, releasing all +the objects in it. When the block is exited with an exception, the pool is not +drained. + +``@autoreleasepool`` may be used in non-ARC translation units, with equivalent +semantics. + +A program is ill-formed if it refers to the ``NSAutoreleasePool`` class. + +.. admonition:: Rationale + + Autorelease pools are clearly important for the compiler to reason about, but + it is far too much to expect the compiler to accurately reason about control + dependencies between two calls. It is also very easy to accidentally forget + to drain an autorelease pool when using the manual API, and this can + significantly inflate the process's high-water-mark. The introduction of a + new scope is unfortunate but basically required for sane interaction with the + rest of the language. Not draining the pool during an unwind is apparently + required by the Objective-C exceptions implementation. + +.. _arc.misc.self: + +``self`` +-------- + +The ``self`` parameter variable of an Objective-C method is never actually +retained by the implementation. It is undefined behavior, or at least +dangerous, to cause an object to be deallocated during a message send to that +object. + +To make this safe, for Objective-C instance methods ``self`` is implicitly +``const`` unless the method is in the :ref:`init family +`. Further, ``self`` is **always** implicitly +``const`` within a class method. + +.. admonition:: Rationale + + The cost of retaining ``self`` in all methods was found to be prohibitive, as + it tends to be live across calls, preventing the optimizer from proving that + the retain and release are unnecessary --- for good reason, as it's quite + possible in theory to cause an object to be deallocated during its execution + without this retain and release. Since it's extremely uncommon to actually + do so, even unintentionally, and since there's no natural way for the + programmer to remove this retain/release pair otherwise (as there is for + other parameters by, say, making the variable ``__unsafe_unretained``), we + chose to make this optimizing assumption and shift some amount of risk to the + user. + +.. _arc.misc.enumeration: + +Fast enumeration iteration variables +------------------------------------ + +If a variable is declared in the condition of an Objective-C fast enumeration +loop, and the variable has no explicit ownership qualifier, then it is +qualified with ``const __strong`` and objects encountered during the +enumeration are not actually retained. + +.. admonition:: Rationale + + This is an optimization made possible because fast enumeration loops promise + to keep the objects retained during enumeration, and the collection itself + cannot be synchronously modified. It can be overridden by explicitly + qualifying the variable with ``__strong``, which will make the variable + mutable again and cause the loop to retain the objects it encounters. + +.. _arc.misc.blocks: + +Blocks +------ + +The implicit ``const`` capture variables created when evaluating a block +literal expression have the same ownership semantics as the local variables +they capture. The capture is performed by reading from the captured variable +and initializing the capture variable with that value; the capture variable is +destroyed when the block literal is, i.e. at the end of the enclosing scope. + +The :ref:`inference ` rules apply equally to +``__block`` variables, which is a shift in semantics from non-ARC, where +``__block`` variables did not implicitly retain during capture. + +``__block`` variables of retainable object owner type are moved off the stack +by initializing the heap copy with the result of moving from the stack copy. + +With the exception of retains done as part of initializing a ``__strong`` +parameter variable or reading a ``__weak`` variable, whenever these semantics +call for retaining a value of block-pointer type, it has the effect of a +``Block_copy``. The optimizer may remove such copies when it sees that the +result is used only as an argument to a call. + +.. _arc.misc.exceptions: + +Exceptions +---------- + +By default in Objective C, ARC is not exception-safe for normal releases: + +* It does not end the lifetime of ``__strong`` variables when their scopes are + abnormally terminated by an exception. +* It does not perform releases which would occur at the end of a + full-expression if that full-expression throws an exception. + +A program may be compiled with the option ``-fobjc-arc-exceptions`` in order to +enable these, or with the option ``-fno-objc-arc-exceptions`` to explicitly +disable them, with the last such argument "winning". + +.. admonition:: Rationale + + The standard Cocoa convention is that exceptions signal programmer error and + are not intended to be recovered from. Making code exceptions-safe by + default would impose severe runtime and code size penalties on code that + typically does not actually care about exceptions safety. Therefore, + ARC-generated code leaks by default on exceptions, which is just fine if the + process is going to be immediately terminated anyway. Programs which do care + about recovering from exceptions should enable the option. + +In Objective-C++, ``-fobjc-arc-exceptions`` is enabled by default. + +.. admonition:: Rationale + + C++ already introduces pervasive exceptions-cleanup code of the sort that ARC + introduces. C++ programmers who have not already disabled exceptions are + much more likely to actual require exception-safety. + +ARC does end the lifetimes of ``__weak`` objects when an exception terminates +their scope unless exceptions are disabled in the compiler. + +.. admonition:: Rationale + + The consequence of a local ``__weak`` object not being destroyed is very + likely to be corruption of the Objective-C runtime, so we want to be safer + here. Of course, potentially massive leaks are about as likely to take down + the process as this corruption is if the program does try to recover from + exceptions. + +.. _arc.misc.interior: + +Interior pointers +----------------- + +An Objective-C method returning a non-retainable pointer may be annotated with +the ``objc_returns_inner_pointer`` attribute to indicate that it returns a +handle to the internal data of an object, and that this reference will be +invalidated if the object is destroyed. When such a message is sent to an +object, the object's lifetime will be extended until at least the earliest of: + +* the last use of the returned pointer, or any pointer derived from it, in the + calling function or +* the autorelease pool is restored to a previous state. + +.. admonition:: Rationale + + Rationale: not all memory and resources are managed with reference counts; it + is common for objects to manage private resources in their own, private way. + Typically these resources are completely encapsulated within the object, but + some classes offer their users direct access for efficiency. If ARC is not + aware of methods that return such "interior" pointers, its optimizations can + cause the owning object to be reclaimed too soon. This attribute informs ARC + that it must tread lightly. + + The extension rules are somewhat intentionally vague. The autorelease pool + limit is there to permit a simple implementation to simply retain and + autorelease the receiver. The other limit permits some amount of + optimization. The phrase "derived from" is intended to encompass the results + both of pointer transformations, such as casts and arithmetic, and of loading + from such derived pointers; furthermore, it applies whether or not such + derivations are applied directly in the calling code or by other utility code + (for example, the C library routine ``strchr``). However, the implementation + never need account for uses after a return from the code which calls the + method returning an interior pointer. + +As an exception, no extension is required if the receiver is loaded directly +from a ``__strong`` object with :ref:`precise lifetime semantics +`. + +.. admonition:: Rationale + + Implicit autoreleases carry the risk of significantly inflating memory use, + so it's important to provide users a way of avoiding these autoreleases. + Tying this to precise lifetime semantics is ideal, as for local variables + this requires a very explicit annotation, which allows ARC to trust the user + with good cheer. + +.. _arc.misc.c-retainable: + +C retainable pointer types +-------------------------- + +A type is a :arc-term:`C retainable pointer type` if it is a pointer to +(possibly qualified) ``void`` or a pointer to a (possibly qualifier) ``struct`` +or ``class`` type. + +.. admonition:: Rationale + + ARC does not manage pointers of CoreFoundation type (or any of the related + families of retainable C pointers which interoperate with Objective-C for + retain/release operation). In fact, ARC does not even know how to + distinguish these types from arbitrary C pointer types. The intent of this + concept is to filter out some obviously non-object types while leaving a hook + for later tightening if a means of exhaustively marking CF types is made + available. + +.. _arc.misc.c-retainable.audit: + +Auditing of C retainable pointer interfaces +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:when-revised:`[beginning Apple 4.0, LLVM 3.1]` + +A C function may be marked with the ``cf_audited_transfer`` attribute to +express that, except as otherwise marked with attributes, it obeys the +parameter (consuming vs. non-consuming) and return (retained vs. non-retained) +conventions for a C function of its name, namely: + +* A parameter of C retainable pointer type is assumed to not be consumed + unless it is marked with the ``cf_consumed`` attribute, and +* A result of C retainable pointer type is assumed to not be returned retained + unless the function is either marked ``cf_returns_retained`` or it follows + the create/copy naming convention and is not marked + ``cf_returns_not_retained``. + +A function obeys the :arc-term:`create/copy` naming convention if its name +contains as a substring: + +* either "Create" or "Copy" not followed by a lowercase letter, or +* either "create" or "copy" not followed by a lowercase letter and + not preceded by any letter, whether uppercase or lowercase. + +A second attribute, ``cf_unknown_transfer``, signifies that a function's +transfer semantics cannot be accurately captured using any of these +annotations. A program is ill-formed if it annotates the same function with +both ``cf_audited_transfer`` and ``cf_unknown_transfer``. + +A pragma is provided to facilitate the mass annotation of interfaces: + +.. code-block:: objc + + #pragma clang arc_cf_code_audited begin + ... + #pragma clang arc_cf_code_audited end + +All C functions declared within the extent of this pragma are treated as if +annotated with the ``cf_audited_transfer`` attribute unless they otherwise have +the ``cf_unknown_transfer`` attribute. The pragma is accepted in all language +modes. A program is ill-formed if it attempts to change files, whether by +including a file or ending the current file, within the extent of this pragma. + +It is possible to test for all the features in this section with +``__has_feature(arc_cf_code_audited)``. + +.. admonition:: Rationale + + A significant inconvenience in ARC programming is the necessity of + interacting with APIs based around C retainable pointers. These features are + designed to make it relatively easy for API authors to quickly review and + annotate their interfaces, in turn improving the fidelity of tools such as + the static analyzer and ARC. The single-file restriction on the pragma is + designed to eliminate the risk of accidentally annotating some other header's + interfaces. + +.. _arc.runtime: + +Runtime support +=============== + +This section describes the interaction between the ARC runtime and the code +generated by the ARC compiler. This is not part of the ARC language +specification; instead, it is effectively a language-specific ABI supplement, +akin to the "Itanium" generic ABI for C++. + +Ownership qualification does not alter the storage requirements for objects, +except that it is undefined behavior if a ``__weak`` object is inadequately +aligned for an object of type ``id``. The other qualifiers may be used on +explicitly under-aligned memory. + +The runtime tracks ``__weak`` objects which holds non-null values. It is +undefined behavior to direct modify a ``__weak`` object which is being tracked +by the runtime except through an +:ref:`objc_storeWeak `, +:ref:`objc_destroyWeak `, or +:ref:`objc_moveWeak ` call. + +The runtime must provide a number of new entrypoints which the compiler may +emit, which are described in the remainder of this section. + +.. admonition:: Rationale + + Several of these functions are semantically equivalent to a message send; we + emit calls to C functions instead because: + + * the machine code to do so is significantly smaller, + * it is much easier to recognize the C functions in the ARC optimizer, and + * a sufficient sophisticated runtime may be able to avoid the message send in + common cases. + + Several other of these functions are "fused" operations which can be + described entirely in terms of other operations. We use the fused operations + primarily as a code-size optimization, although in some cases there is also a + real potential for avoiding redundant operations in the runtime. + +.. _arc.runtime.objc_autorelease: + +``id objc_autorelease(id value);`` +---------------------------------- + +*Precondition:* ``value`` is null or a pointer to a valid object. + +If ``value`` is null, this call has no effect. Otherwise, it adds the object +to the innermost autorelease pool exactly as if the object had been sent the +``autorelease`` message. + +Always returns ``value``. + +.. _arc.runtime.objc_autoreleasePoolPop: + +``void objc_autoreleasePoolPop(void *pool);`` +--------------------------------------------- + +*Precondition:* ``pool`` is the result of a previous call to +:ref:`objc_autoreleasePoolPush ` on the +current thread, where neither ``pool`` nor any enclosing pool have previously +been popped. + +Releases all the objects added to the given autorelease pool and any +autorelease pools it encloses, then sets the current autorelease pool to the +pool directly enclosing ``pool``. + +.. _arc.runtime.objc_autoreleasePoolPush: + +``void *objc_autoreleasePoolPush(void);`` +----------------------------------------- + +Creates a new autorelease pool that is enclosed by the current pool, makes that +the current pool, and returns an opaque "handle" to it. + +.. admonition:: Rationale + + While the interface is described as an explicit hierarchy of pools, the rules + allow the implementation to just keep a stack of objects, using the stack + depth as the opaque pool handle. + +.. _arc.runtime.objc_autoreleaseReturnValue: + +``id objc_autoreleaseReturnValue(id value);`` +--------------------------------------------- + +*Precondition:* ``value`` is null or a pointer to a valid object. + +If ``value`` is null, this call has no effect. Otherwise, it makes a best +effort to hand off ownership of a retain count on the object to a call to +:ref:`objc_retainAutoreleasedReturnValue +` for the same object in an +enclosing call frame. If this is not possible, the object is autoreleased as +above. + +Always returns ``value``. + +.. _arc.runtime.objc_copyWeak: + +``void objc_copyWeak(id *dest, id *src);`` +------------------------------------------ + +*Precondition:* ``src`` is a valid pointer which either contains a null pointer +or has been registered as a ``__weak`` object. ``dest`` is a valid pointer +which has not been registered as a ``__weak`` object. + +``dest`` is initialized to be equivalent to ``src``, potentially registering it +with the runtime. Equivalent to the following code: + +.. code-block:: objc + + void objc_copyWeak(id *dest, id *src) { + objc_release(objc_initWeak(dest, objc_loadWeakRetained(src))); + } + +Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``. + +.. _arc.runtime.objc_destroyWeak: + +``void objc_destroyWeak(id *object);`` +-------------------------------------- + +*Precondition:* ``object`` is a valid pointer which either contains a null +pointer or has been registered as a ``__weak`` object. + +``object`` is unregistered as a weak object, if it ever was. The current value +of ``object`` is left unspecified; otherwise, equivalent to the following code: + +.. code-block:: objc + + void objc_destroyWeak(id *object) { + objc_storeWeak(object, nil); + } + +Does not need to be atomic with respect to calls to ``objc_storeWeak`` on +``object``. + +.. _arc.runtime.objc_initWeak: + +``id objc_initWeak(id *object, id value);`` +------------------------------------------- + +*Precondition:* ``object`` is a valid pointer which has not been registered as +a ``__weak`` object. ``value`` is null or a pointer to a valid object. + +If ``value`` is a null pointer or the object to which it points has begun +deallocation, ``object`` is zero-initialized. Otherwise, ``object`` is +registered as a ``__weak`` object pointing to ``value``. Equivalent to the +following code: + +.. code-block:: objc + + id objc_initWeak(id *object, id value) { + *object = nil; + return objc_storeWeak(object, value); + } + +Returns the value of ``object`` after the call. + +Does not need to be atomic with respect to calls to ``objc_storeWeak`` on +``object``. + +.. _arc.runtime.objc_loadWeak: + +``id objc_loadWeak(id *object);`` +--------------------------------- + +*Precondition:* ``object`` is a valid pointer which either contains a null +pointer or has been registered as a ``__weak`` object. + +If ``object`` is registered as a ``__weak`` object, and the last value stored +into ``object`` has not yet been deallocated or begun deallocation, retains and +autoreleases that value and returns it. Otherwise returns null. Equivalent to +the following code: + +.. code-block:: objc + + id objc_loadWeak(id *object) { + return objc_autorelease(objc_loadWeakRetained(object)); + } + +Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``. + +.. admonition:: Rationale + + Loading weak references would be inherently prone to race conditions without + the retain. + +.. _arc.runtime.objc_loadWeakRetained: + +``id objc_loadWeakRetained(id *object);`` +----------------------------------------- + +*Precondition:* ``object`` is a valid pointer which either contains a null +pointer or has been registered as a ``__weak`` object. + +If ``object`` is registered as a ``__weak`` object, and the last value stored +into ``object`` has not yet been deallocated or begun deallocation, retains +that value and returns it. Otherwise returns null. + +Must be atomic with respect to calls to ``objc_storeWeak`` on ``object``. + +.. _arc.runtime.objc_moveWeak: + +``void objc_moveWeak(id *dest, id *src);`` +------------------------------------------ + +*Precondition:* ``src`` is a valid pointer which either contains a null pointer +or has been registered as a ``__weak`` object. ``dest`` is a valid pointer +which has not been registered as a ``__weak`` object. + +``dest`` is initialized to be equivalent to ``src``, potentially registering it +with the runtime. ``src`` may then be left in its original state, in which +case this call is equivalent to :ref:`objc_copyWeak +`, or it may be left as null. + +Must be atomic with respect to calls to ``objc_storeWeak`` on ``src``. + +.. _arc.runtime.objc_release: + +``void objc_release(id value);`` +-------------------------------- + +*Precondition:* ``value`` is null or a pointer to a valid object. + +If ``value`` is null, this call has no effect. Otherwise, it performs a +release operation exactly as if the object had been sent the ``release`` +message. + +.. _arc.runtime.objc_retain: + +``id objc_retain(id value);`` +----------------------------- + +*Precondition:* ``value`` is null or a pointer to a valid object. + +If ``value`` is null, this call has no effect. Otherwise, it performs a retain +operation exactly as if the object had been sent the ``retain`` message. + +Always returns ``value``. + +.. _arc.runtime.objc_retainAutorelease: + +``id objc_retainAutorelease(id value);`` +---------------------------------------- + +*Precondition:* ``value`` is null or a pointer to a valid object. + +If ``value`` is null, this call has no effect. Otherwise, it performs a retain +operation followed by an autorelease operation. Equivalent to the following +code: + +.. code-block:: objc + + id objc_retainAutorelease(id value) { + return objc_autorelease(objc_retain(value)); + } + +Always returns ``value``. + +.. _arc.runtime.objc_retainAutoreleaseReturnValue: + +``id objc_retainAutoreleaseReturnValue(id value);`` +--------------------------------------------------- + +*Precondition:* ``value`` is null or a pointer to a valid object. + +If ``value`` is null, this call has no effect. Otherwise, it performs a retain +operation followed by the operation described in +:ref:`objc_autoreleaseReturnValue `. +Equivalent to the following code: + +.. code-block:: objc + + id objc_retainAutoreleaseReturnValue(id value) { + return objc_autoreleaseReturnValue(objc_retain(value)); + } + +Always returns ``value``. + +.. _arc.runtime.objc_retainAutoreleasedReturnValue: + +``id objc_retainAutoreleasedReturnValue(id value);`` +---------------------------------------------------- + +*Precondition:* ``value`` is null or a pointer to a valid object. + +If ``value`` is null, this call has no effect. Otherwise, it attempts to +accept a hand off of a retain count from a call to +:ref:`objc_autoreleaseReturnValue ` on +``value`` in a recently-called function or something it calls. If that fails, +it performs a retain operation exactly like :ref:`objc_retain +`. + +Always returns ``value``. + +.. _arc.runtime.objc_retainBlock: + +``id objc_retainBlock(id value);`` +---------------------------------- + +*Precondition:* ``value`` is null or a pointer to a valid block object. + +If ``value`` is null, this call has no effect. Otherwise, if the block pointed +to by ``value`` is still on the stack, it is copied to the heap and the address +of the copy is returned. Otherwise a retain operation is performed on the +block exactly as if it had been sent the ``retain`` message. + +.. _arc.runtime.objc_storeStrong: + +``id objc_storeStrong(id *object, id value);`` +---------------------------------------------- + +*Precondition:* ``object`` is a valid pointer to a ``__strong`` object which is +adequately aligned for a pointer. ``value`` is null or a pointer to a valid +object. + +Performs the complete sequence for assigning to a ``__strong`` object of +non-block type [*]_. Equivalent to the following code: + +.. code-block:: objc + + id objc_storeStrong(id *object, id value) { + value = [value retain]; + id oldValue = *object; + *object = value; + [oldValue release]; + return value; + } + +Always returns ``value``. + +.. [*] This does not imply that a ``__strong`` object of block type is an + invalid argument to this function. Rather it implies that an ``objc_retain`` + and not an ``objc_retainBlock`` operation will be emitted if the argument is + a block. + +.. _arc.runtime.objc_storeWeak: + +``id objc_storeWeak(id *object, id value);`` +-------------------------------------------- + +*Precondition:* ``object`` is a valid pointer which either contains a null +pointer or has been registered as a ``__weak`` object. ``value`` is null or a +pointer to a valid object. + +If ``value`` is a null pointer or the object to which it points has begun +deallocation, ``object`` is assigned null and unregistered as a ``__weak`` +object. Otherwise, ``object`` is registered as a ``__weak`` object or has its +registration updated to point to ``value``. + +Returns the value of ``object`` after the call. + diff --git a/docs/Block-ABI-Apple.rst b/docs/Block-ABI-Apple.rst new file mode 100644 index 000000000000..08f346447e03 --- /dev/null +++ b/docs/Block-ABI-Apple.rst @@ -0,0 +1,935 @@ +================================== +Block Implementation Specification +================================== + +.. contents:: + :local: + +History +======= + +* 2008/7/14 - created. +* 2008/8/21 - revised, C++. +* 2008/9/24 - add ``NULL`` ``isa`` field to ``__block`` storage. +* 2008/10/1 - revise block layout to use a ``static`` descriptor structure. +* 2008/10/6 - revise block layout to use an unsigned long int flags. +* 2008/10/28 - specify use of ``_Block_object_assign`` and + ``_Block_object_dispose`` for all "Object" types in helper functions. +* 2008/10/30 - revise new layout to have invoke function in same place. +* 2008/10/30 - add ``__weak`` support. +* 2010/3/16 - rev for stret return, signature field. +* 2010/4/6 - improved wording. +* 2013/1/6 - improved wording and converted to rst. + +This document describes the Apple ABI implementation specification of Blocks. + +The first shipping version of this ABI is found in Mac OS X 10.6, and shall be +referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI +contract with the runtime and the compiler, and, as necessary, will be referred +to as ABI.2010.3.16. + +Since the Apple ABI references symbols from other elements of the system, any +attempt to use this ABI on systems prior to SnowLeopard is undefined. + +High Level +========== + +The ABI of ``Blocks`` consist of their layout and the runtime functions required +by the compiler. A ``Block`` consists of a structure of the following form: + +.. code-block:: c + + struct Block_literal_1 { + void *isa; // initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock + int flags; + int reserved; + void (*invoke)(void *, ...); + struct Block_descriptor_1 { + unsigned long int reserved; // NULL + unsigned long int size; // sizeof(struct Block_literal_1) + // optional helper functions + void (*copy_helper)(void *dst, void *src); // IFF (1<<25) + void (*dispose_helper)(void *src); // IFF (1<<25) + // required ABI.2010.3.16 + const char *signature; // IFF (1<<30) + } *descriptor; + // imported variables + }; + +The following flags bits are in use thusly for a possible ABI.2010.3.16: + +.. code-block:: c + + enum { + BLOCK_HAS_COPY_DISPOSE = (1 << 25), + BLOCK_HAS_CTOR = (1 << 26), // helpers have C++ code + BLOCK_IS_GLOBAL = (1 << 28), + BLOCK_HAS_STRET = (1 << 29), // IFF BLOCK_HAS_SIGNATURE + BLOCK_HAS_SIGNATURE = (1 << 30), + }; + +In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime - +it had been a transitional marker that did not get deleted after the +transition. This bit is now paired with (1<<30), and represented as the pair +(3<<30), for the following combinations of valid bit settings, and their +meanings: + +.. code-block:: c + + switch (flags & (3<<29)) { + case (0<<29): 10.6.ABI, no signature field available + case (1<<29): 10.6.ABI, no signature field available + case (2<<29): ABI.2010.3.16, regular calling convention, presence of signature field + case (3<<29): ABI.2010.3.16, stret calling convention, presence of signature field, + } + +The signature field is not always populated. + +The following discussions are presented as 10.6.ABI otherwise. + +``Block`` literals may occur within functions where the structure is created in +stack local memory. They may also appear as initialization expressions for +``Block`` variables of global or ``static`` local variables. + +When a ``Block`` literal expression is evaluated the stack based structure is +initialized as follows: + +1. A ``static`` descriptor structure is declared and initialized as follows: + + a. The ``invoke`` function pointer is set to a function that takes the + ``Block`` structure as its first argument and the rest of the arguments (if + any) to the ``Block`` and executes the ``Block`` compound statement. + + b. The ``size`` field is set to the size of the following ``Block`` literal + structure. + + c. The ``copy_helper`` and ``dispose_helper`` function pointers are set to + respective helper functions if they are required by the ``Block`` literal. + +2. A stack (or global) ``Block`` literal data structure is created and + initialized as follows: + + a. The ``isa`` field is set to the address of the external + ``_NSConcreteStackBlock``, which is a block of uninitialized memory supplied + in ``libSystem``, or ``_NSConcreteGlobalBlock`` if this is a static or file + level ``Block`` literal. + + b. The ``flags`` field is set to zero unless there are variables imported + into the ``Block`` that need helper functions for program level + ``Block_copy()`` and ``Block_release()`` operations, in which case the + (1<<25) flags bit is set. + +As an example, the ``Block`` literal expression: + +.. code-block:: c + + ^ { printf("hello world\n"); } + +would cause the following to be created on a 32-bit system: + +.. code-block:: c + + struct __block_literal_1 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_1 *); + struct __block_descriptor_1 *descriptor; + }; + + void __block_invoke_1(struct __block_literal_1 *_block) { + printf("hello world\n"); + } + + static struct __block_descriptor_1 { + unsigned long int reserved; + unsigned long int Block_size; + } __block_descriptor_1 = { 0, sizeof(struct __block_literal_1), __block_invoke_1 }; + +and where the ``Block`` literal itself appears: + +.. code-block:: c + + struct __block_literal_1 _block_literal = { + &_NSConcreteStackBlock, + (1<<29), , + __block_invoke_1, + &__block_descriptor_1 + }; + +A ``Block`` imports other ``Block`` references, ``const`` copies of other +variables, and variables marked ``__block``. In Objective-C, variables may +additionally be objects. + +When a ``Block`` literal expression is used as the initial value of a global +or ``static`` local variable, it is initialized as follows: + +.. code-block:: c + + struct __block_literal_1 __block_literal_1 = { + &_NSConcreteGlobalBlock, + (1<<28)|(1<<29), , + __block_invoke_1, + &__block_descriptor_1 + }; + +that is, a different address is provided as the first value and a particular +(1<<28) bit is set in the ``flags`` field, and otherwise it is the same as for +stack based ``Block`` literals. This is an optimization that can be used for +any ``Block`` literal that imports no ``const`` or ``__block`` storage +variables. + +Imported Variables +================== + +Variables of ``auto`` storage class are imported as ``const`` copies. Variables +of ``__block`` storage class are imported as a pointer to an enclosing data +structure. Global variables are simply referenced and not considered as +imported. + +Imported ``const`` copy variables +--------------------------------- + +Automatic storage variables not marked with ``__block`` are imported as +``const`` copies. + +The simplest example is that of importing a variable of type ``int``: + +.. code-block:: c + + int x = 10; + void (^vv)(void) = ^{ printf("x is %d\n", x); } + x = 11; + vv(); + +which would be compiled to: + +.. code-block:: c + + struct __block_literal_2 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_2 *); + struct __block_descriptor_2 *descriptor; + const int x; + }; + + void __block_invoke_2(struct __block_literal_2 *_block) { + printf("x is %d\n", _block->x); + } + + static struct __block_descriptor_2 { + unsigned long int reserved; + unsigned long int Block_size; + } __block_descriptor_2 = { 0, sizeof(struct __block_literal_2) }; + +and: + +.. code-block:: c + + struct __block_literal_2 __block_literal_2 = { + &_NSConcreteStackBlock, + (1<<29), , + __block_invoke_2, + &__block_descriptor_2, + x + }; + +In summary, scalars, structures, unions, and function pointers are generally +imported as ``const`` copies with no need for helper functions. + +Imported ``const`` copy of ``Block`` reference +---------------------------------------------- + +The first case where copy and dispose helper functions are required is for the +case of when a ``Block`` itself is imported. In this case both a +``copy_helper`` function and a ``dispose_helper`` function are needed. The +``copy_helper`` function is passed both the existing stack based pointer and the +pointer to the new heap version and should call back into the runtime to +actually do the copy operation on the imported fields within the ``Block``. The +runtime functions are all described in :ref:`RuntimeHelperFunctions`. + +A quick example: + +.. code-block:: c + + void (^existingBlock)(void) = ...; + void (^vv)(void) = ^{ existingBlock(); } + vv(); + + struct __block_literal_3 { + ...; // existing block + }; + + struct __block_literal_4 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_4 *); + struct __block_literal_3 *const existingBlock; + }; + + void __block_invoke_4(struct __block_literal_2 *_block) { + __block->existingBlock->invoke(__block->existingBlock); + } + + void __block_copy_4(struct __block_literal_4 *dst, struct __block_literal_4 *src) { + //_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0); + _Block_object_assign(&dst->existingBlock, src->existingBlock, BLOCK_FIELD_IS_BLOCK); + } + + void __block_dispose_4(struct __block_literal_4 *src) { + // was _Block_destroy + _Block_object_dispose(src->existingBlock, BLOCK_FIELD_IS_BLOCK); + } + + static struct __block_descriptor_4 { + unsigned long int reserved; + unsigned long int Block_size; + void (*copy_helper)(struct __block_literal_4 *dst, struct __block_literal_4 *src); + void (*dispose_helper)(struct __block_literal_4 *); + } __block_descriptor_4 = { + 0, + sizeof(struct __block_literal_4), + __block_copy_4, + __block_dispose_4, + }; + +and where said ``Block`` is used: + +.. code-block:: c + + struct __block_literal_4 _block_literal = { + &_NSConcreteStackBlock, + (1<<25)|(1<<29), + __block_invoke_4, + & __block_descriptor_4 + existingBlock, + }; + +Importing ``__attribute__((NSObject))`` variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GCC introduces ``__attribute__((NSObject))`` on structure pointers to mean "this +is an object". This is useful because many low level data structures are +declared as opaque structure pointers, e.g. ``CFStringRef``, ``CFArrayRef``, +etc. When used from C, however, these are still really objects and are the +second case where that requires copy and dispose helper functions to be +generated. The copy helper functions generated by the compiler should use the +``_Block_object_assign`` runtime helper function and in the dispose helper the +``_Block_object_dispose`` runtime helper function should be called. + +For example, ``Block`` foo in the following: + +.. code-block:: c + + struct Opaque *__attribute__((NSObject)) objectPointer = ...; + ... + void (^foo)(void) = ^{ CFPrint(objectPointer); }; + +would have the following helper functions generated: + +.. code-block:: c + + void __block_copy_foo(struct __block_literal_5 *dst, struct __block_literal_5 *src) { + _Block_object_assign(&dst->objectPointer, src-> objectPointer, BLOCK_FIELD_IS_OBJECT); + } + + void __block_dispose_foo(struct __block_literal_5 *src) { + _Block_object_dispose(src->objectPointer, BLOCK_FIELD_IS_OBJECT); + } + +Imported ``__block`` marked variables +------------------------------------- + +Layout of ``__block`` marked variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The compiler must embed variables that are marked ``__block`` in a specialized +structure of the form: + +.. code-block:: c + + struct _block_byref_foo { + void *isa; + struct Block_byref *forwarding; + int flags; //refcount; + int size; + typeof(marked_variable) marked_variable; + }; + +Variables of certain types require helper functions for when ``Block_copy()`` +and ``Block_release()`` are performed upon a referencing ``Block``. At the "C" +level only variables that are of type ``Block`` or ones that have +``__attribute__((NSObject))`` marked require helper functions. In Objective-C +objects require helper functions and in C++ stack based objects require helper +functions. Variables that require helper functions use the form: + +.. code-block:: c + + struct _block_byref_foo { + void *isa; + struct _block_byref_foo *forwarding; + int flags; //refcount; + int size; + // helper functions called via Block_copy() and Block_release() + void (*byref_keep)(void *dst, void *src); + void (*byref_dispose)(void *); + typeof(marked_variable) marked_variable; + }; + +The structure is initialized such that: + + a. The ``forwarding`` pointer is set to the beginning of its enclosing + structure. + + b. The ``size`` field is initialized to the total size of the enclosing + structure. + + c. The ``flags`` field is set to either 0 if no helper functions are needed + or (1<<25) if they are. + + d. The helper functions are initialized (if present). + + e. The variable itself is set to its initial value. + + f. The ``isa`` field is set to ``NULL``. + +Access to ``__block`` variables from within its lexical scope +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to "move" the variable to the heap upon a ``copy_helper`` operation the +compiler must rewrite access to such a variable to be indirect through the +structures ``forwarding`` pointer. For example: + +.. code-block:: c + + int __block i = 10; + i = 11; + +would be rewritten to be: + +.. code-block:: c + + struct _block_byref_i { + void *isa; + struct _block_byref_i *forwarding; + int flags; //refcount; + int size; + int captured_i; + } i = { NULL, &i, 0, sizeof(struct _block_byref_i), 10 }; + + i.forwarding->captured_i = 11; + +In the case of a ``Block`` reference variable being marked ``__block`` the +helper code generated must use the ``_Block_object_assign`` and +``_Block_object_dispose`` routines supplied by the runtime to make the +copies. For example: + +.. code-block:: c + + __block void (voidBlock)(void) = blockA; + voidBlock = blockB; + +would translate into: + +.. code-block:: c + + struct _block_byref_voidBlock { + void *isa; + struct _block_byref_voidBlock *forwarding; + int flags; //refcount; + int size; + void (*byref_keep)(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src); + void (*byref_dispose)(struct _block_byref_voidBlock *); + void (^captured_voidBlock)(void); + }; + + void _block_byref_keep_helper(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) { + //_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0); + _Block_object_assign(&dst->captured_voidBlock, src->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER); + } + + void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) { + //_Block_destroy(param->captured_voidBlock, 0); + _Block_object_dispose(param->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER)} + +and: + +.. code-block:: c + + struct _block_byref_voidBlock voidBlock = {( .forwarding=&voidBlock, .flags=(1<<25), .size=sizeof(struct _block_byref_voidBlock *), + .byref_keep=_block_byref_keep_helper, .byref_dispose=_block_byref_dispose_helper, + .captured_voidBlock=blockA )}; + + voidBlock.forwarding->captured_voidBlock = blockB; + +Importing ``__block`` variables into ``Blocks`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A ``Block`` that uses a ``__block`` variable in its compound statement body must +import the variable and emit ``copy_helper`` and ``dispose_helper`` helper +functions that, in turn, call back into the runtime to actually copy or release +the ``byref`` data block using the functions ``_Block_object_assign`` and +``_Block_object_dispose``. + +For example: + +.. code-block:: c + + int __block i = 2; + functioncall(^{ i = 10; }); + +would translate to: + +.. code-block:: c + + struct _block_byref_i { + void *isa; // set to NULL + struct _block_byref_voidBlock *forwarding; + int flags; //refcount; + int size; + void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src); + void (*byref_dispose)(struct _block_byref_i *); + int captured_i; + }; + + + struct __block_literal_5 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_5 *); + struct __block_descriptor_5 *descriptor; + struct _block_byref_i *i_holder; + }; + + void __block_invoke_5(struct __block_literal_5 *_block) { + _block->forwarding->captured_i = 10; + } + + void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) { + //_Block_byref_assign_copy(&dst->captured_i, src->captured_i); + _Block_object_assign(&dst->captured_i, src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER); + } + + void __block_dispose_5(struct __block_literal_5 *src) { + //_Block_byref_release(src->captured_i); + _Block_object_dispose(src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER); + } + + static struct __block_descriptor_5 { + unsigned long int reserved; + unsigned long int Block_size; + void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src); + void (*dispose_helper)(struct __block_literal_5 *); + } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5) __block_copy_5, __block_dispose_5 }; + +and: + +.. code-block:: c + + struct _block_byref_i i = {( .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i) )}; + struct __block_literal_5 _block_literal = { + &_NSConcreteStackBlock, + (1<<25)|(1<<29), , + __block_invoke_5, + &__block_descriptor_5, + 2, + }; + +Importing ``__attribute__((NSObject))`` ``__block`` variables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A ``__block`` variable that is also marked ``__attribute__((NSObject))`` should +have ``byref_keep`` and ``byref_dispose`` helper functions that use +``_Block_object_assign`` and ``_Block_object_dispose``. + +``__block`` escapes +^^^^^^^^^^^^^^^^^^^ + +Because ``Blocks`` referencing ``__block`` variables may have ``Block_copy()`` +performed upon them the underlying storage for the variables may move to the +heap. In Objective-C Garbage Collection Only compilation environments the heap +used is the garbage collected one and no further action is required. Otherwise +the compiler must issue a call to potentially release any heap storage for +``__block`` variables at all escapes or terminations of their scope. The call +should be: + +.. code-block:: c + + _Block_object_dispose(&_block_byref_foo, BLOCK_FIELD_IS_BYREF); + +Nesting +^^^^^^^ + +``Blocks`` may contain ``Block`` literal expressions. Any variables used within +inner blocks are imported into all enclosing ``Block`` scopes even if the +variables are not used. This includes ``const`` imports as well as ``__block`` +variables. + +Objective C Extensions to ``Blocks`` +==================================== + +Importing Objects +----------------- + +Objects should be treated as ``__attribute__((NSObject))`` variables; all +``copy_helper``, ``dispose_helper``, ``byref_keep``, and ``byref_dispose`` +helper functions should use ``_Block_object_assign`` and +``_Block_object_dispose``. There should be no code generated that uses +``*-retain`` or ``*-release`` methods. + +``Blocks`` as Objects +--------------------- + +The compiler will treat ``Blocks`` as objects when synthesizing property setters +and getters, will characterize them as objects when generating garbage +collection strong and weak layout information in the same manner as objects, and +will issue strong and weak write-barrier assignments in the same manner as +objects. + +``__weak __block`` Support +-------------------------- + +Objective-C (and Objective-C++) support the ``__weak`` attribute on ``__block`` +variables. Under normal circumstances the compiler uses the Objective-C runtime +helper support functions ``objc_assign_weak`` and ``objc_read_weak``. Both +should continue to be used for all reads and writes of ``__weak __block`` +variables: + +.. code-block:: c + + objc_read_weak(&block->byref_i->forwarding->i) + +The ``__weak`` variable is stored in a ``_block_byref_foo`` structure and the +``Block`` has copy and dispose helpers for this structure that call: + +.. code-block:: c + + _Block_object_assign(&dest->_block_byref_i, src-> _block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF); + +and: + +.. code-block:: c + + _Block_object_dispose(src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF); + +In turn, the ``block_byref`` copy support helpers distinguish between whether +the ``__block`` variable is a ``Block`` or not and should either call: + +.. code-block:: c + + _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_OBJECT | BLOCK_BYREF_CALLER); + +for something declared as an object or: + +.. code-block:: c + + _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER); + +for something declared as a ``Block``. + +A full example follows: + +.. code-block:: c + + __block __weak id obj = ; + functioncall(^{ [obj somemessage]; }); + +would translate to: + +.. code-block:: c + + struct _block_byref_obj { + void *isa; // uninitialized + struct _block_byref_obj *forwarding; + int flags; //refcount; + int size; + void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src); + void (*byref_dispose)(struct _block_byref_i *); + id captured_obj; + }; + + void _block_byref_obj_keep(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) { + //_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0); + _Block_object_assign(&dst->captured_obj, src->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER); + } + + void _block_byref_obj_dispose(struct _block_byref_voidBlock *param) { + //_Block_destroy(param->captured_obj, 0); + _Block_object_dispose(param->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER); + }; + +for the block ``byref`` part and: + +.. code-block:: c + + struct __block_literal_5 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_5 *); + struct __block_descriptor_5 *descriptor; + struct _block_byref_obj *byref_obj; + }; + + void __block_invoke_5(struct __block_literal_5 *_block) { + [objc_read_weak(&_block->byref_obj->forwarding->captured_obj) somemessage]; + } + + void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) { + //_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj); + _Block_object_assign(&dst->byref_obj, src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK); + } + + void __block_dispose_5(struct __block_literal_5 *src) { + //_Block_byref_release(src->byref_obj); + _Block_object_dispose(src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK); + } + + static struct __block_descriptor_5 { + unsigned long int reserved; + unsigned long int Block_size; + void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src); + void (*dispose_helper)(struct __block_literal_5 *); + } __block_descriptor_5 = { 0, sizeof(struct __block_literal_5), __block_copy_5, __block_dispose_5 }; + +and within the compound statement: + +.. code-block:: c + + truct _block_byref_obj obj = {( .forwarding=&obj, .flags=(1<<25), .size=sizeof(struct _block_byref_obj), + .byref_keep=_block_byref_obj_keep, .byref_dispose=_block_byref_obj_dispose, + .captured_obj = )}; + + truct __block_literal_5 _block_literal = { + &_NSConcreteStackBlock, + (1<<25)|(1<<29), , + __block_invoke_5, + &__block_descriptor_5, + &obj, // a reference to the on-stack structure containing "captured_obj" + }; + + + functioncall(_block_literal->invoke(&_block_literal)); + +C++ Support +=========== + +Within a block stack based C++ objects are copied into ``const`` copies using +the copy constructor. It is an error if a stack based C++ object is used within +a block if it does not have a copy constructor. In addition both copy and +destroy helper routines must be synthesized for the block to support the +``Block_copy()`` operation, and the flags work marked with the (1<<26) bit in +addition to the (1<<25) bit. The copy helper should call the constructor using +appropriate offsets of the variable within the supplied stack based block source +and heap based destination for all ``const`` constructed copies, and similarly +should call the destructor in the destroy routine. + +As an example, suppose a C++ class ``FOO`` existed with a copy constructor. +Within a code block a stack version of a ``FOO`` object is declared and used +within a ``Block`` literal expression: + +.. code-block:: c++ + + { + FOO foo; + void (^block)(void) = ^{ printf("%d\n", foo.value()); }; + } + +The compiler would synthesize: + +.. code-block:: c++ + + struct __block_literal_10 { + void *isa; + int flags; + int reserved; + void (*invoke)(struct __block_literal_10 *); + struct __block_descriptor_10 *descriptor; + const FOO foo; + }; + + void __block_invoke_10(struct __block_literal_10 *_block) { + printf("%d\n", _block->foo.value()); + } + + void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) { + FOO_ctor(&dst->foo, &src->foo); + } + + void __block_dispose_10(struct __block_literal_10 *src) { + FOO_dtor(&src->foo); + } + + static struct __block_descriptor_10 { + unsigned long int reserved; + unsigned long int Block_size; + void (*copy_helper)(struct __block_literal_10 *dst, struct __block_literal_10 *src); + void (*dispose_helper)(struct __block_literal_10 *); + } __block_descriptor_10 = { 0, sizeof(struct __block_literal_10), __block_copy_10, __block_dispose_10 }; + +and the code would be: + +.. code-block:: c++ + + { + FOO foo; + comp_ctor(&foo); // default constructor + struct __block_literal_10 _block_literal = { + &_NSConcreteStackBlock, + (1<<25)|(1<<26)|(1<<29), , + __block_invoke_10, + &__block_descriptor_10, + }; + comp_ctor(&_block_literal->foo, &foo); // const copy into stack version + struct __block_literal_10 &block = &_block_literal; // assign literal to block variable + block->invoke(block); // invoke block + comp_dtor(&_block_literal->foo); // destroy stack version of const block copy + comp_dtor(&foo); // destroy original version + } + + +C++ objects stored in ``__block`` storage start out on the stack in a +``block_byref`` data structure as do other variables. Such objects (if not +``const`` objects) must support a regular copy constructor. The ``block_byref`` +data structure will have copy and destroy helper routines synthesized by the +compiler. The copy helper will have code created to perform the copy +constructor based on the initial stack ``block_byref`` data structure, and will +also set the (1<<26) bit in addition to the (1<<25) bit. The destroy helper +will have code to do the destructor on the object stored within the supplied +``block_byref`` heap data structure. For example, + +.. code-block:: c++ + + __block FOO blockStorageFoo; + +requires the normal constructor for the embedded ``blockStorageFoo`` object: + +.. code-block:: c++ + + FOO_ctor(& _block_byref_blockStorageFoo->blockStorageFoo); + +and at scope termination the destructor: + +.. code-block:: c++ + + FOO_dtor(& _block_byref_blockStorageFoo->blockStorageFoo); + +Note that the forwarding indirection is *NOT* used. + +The compiler would need to generate (if used from a block literal) the following +copy/dispose helpers: + +.. code-block:: c++ + + void _block_byref_obj_keep(struct _block_byref_blockStorageFoo *dst, struct _block_byref_blockStorageFoo *src) { + FOO_ctor(&dst->blockStorageFoo, &src->blockStorageFoo); + } + + void _block_byref_obj_dispose(struct _block_byref_blockStorageFoo *src) { + FOO_dtor(&src->blockStorageFoo); + } + +for the appropriately named constructor and destructor for the class/struct +``FOO``. + +To support member variable and function access the compiler will synthesize a +``const`` pointer to a block version of the ``this`` pointer. + +.. _RuntimeHelperFunctions: + +Runtime Helper Functions +======================== + +The runtime helper functions are described in +``/usr/local/include/Block_private.h``. To summarize their use, a ``Block`` +requires copy/dispose helpers if it imports any block variables, ``__block`` +storage variables, ``__attribute__((NSObject))`` variables, or C++ ``const`` +copied objects with constructor/destructors. The (1<<26) bit is set and +functions are generated. + +The block copy helper function should, for each of the variables of the type +mentioned above, call: + +.. code-block:: c + + _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_); + +in the copy helper and: + +.. code-block:: c + + _Block_object_dispose(->target, BLOCK_FIELD_); + +in the dispose helper where ```` is: + +.. code-block:: c + + enum { + BLOCK_FIELD_IS_OBJECT = 3, // id, NSObject, __attribute__((NSObject)), block, ... + BLOCK_FIELD_IS_BLOCK = 7, // a block variable + BLOCK_FIELD_IS_BYREF = 8, // the on stack structure holding the __block variable + + BLOCK_FIELD_IS_WEAK = 16, // declared __weak + + BLOCK_BYREF_CALLER = 128, // called from byref copy/dispose helpers + }; + +and of course the constructors/destructors for ``const`` copied C++ objects. + +The ``block_byref`` data structure similarly requires copy/dispose helpers for +block variables, ``__attribute__((NSObject))`` variables, or C++ ``const`` +copied objects with constructor/destructors, and again the (1<<26) bit is set +and functions are generated in the same manner. + +Under ObjC we allow ``__weak`` as an attribute on ``__block`` variables, and +this causes the addition of ``BLOCK_FIELD_IS_WEAK`` orred onto the +``BLOCK_FIELD_IS_BYREF`` flag when copying the ``block_byref`` structure in the +``Block`` copy helper, and onto the ``BLOCK_FIELD_`` field within the +``block_byref`` copy/dispose helper calls. + +The prototypes, and summary, of the helper functions are: + +.. code-block:: c + + /* Certain field types require runtime assistance when being copied to the + heap. The following function is used to copy fields of types: blocks, + pointers to byref structures, and objects (including + __attribute__((NSObject)) pointers. BLOCK_FIELD_IS_WEAK is orthogonal to + the other choices which are mutually exclusive. Only in a Block copy + helper will one see BLOCK_FIELD_IS_BYREF. + */ + void _Block_object_assign(void *destAddr, const void *object, const int flags); + + /* Similarly a compiler generated dispose helper needs to call back for each + field of the byref data structure. (Currently the implementation only + packs one field into the byref structure but in principle there could be + more). The same flags used in the copy helper should be used for each + call generated to this function: + */ + void _Block_object_dispose(const void *object, const int flags); + +Copyright +========= + +Copyright 2008-2010 Apple, Inc. +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/docs/Block-ABI-Apple.txt b/docs/Block-ABI-Apple.txt index 917059b4829c..94a4d18e08f0 100644 --- a/docs/Block-ABI-Apple.txt +++ b/docs/Block-ABI-Apple.txt @@ -1,669 +1 @@ -Block Implementation Specification - -Copyright 2008-2010 Apple, Inc. -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - -0. History - -2008/7/14 - created -2008/8/21 - revised, C++ -2008/9/24 - add NULL isa field to __block storage -2008/10/1 - revise block layout to use a static descriptor structure -2008/10/6 - revise block layout to use an unsigned long int flags -2008/10/28 - specify use of _Block_object_assign/dispose for all "Object" types in helper functions -2008/10/30 - revise new layout to have invoke function in same place -2008/10/30 - add __weak support - -2010/3/16 - rev for stret return, signature field -2010/4/6 - improved wording - -This document describes the Apple ABI implementation specification of Blocks. - -The first shipping version of this ABI is found in Mac OS X 10.6, and shall be referred to as 10.6.ABI. As of 2010/3/16, the following describes the ABI contract with the runtime and the compiler, and, as necessary, will be referred to as ABI.2010.3.16. - -Since the Apple ABI references symbols from other elements of the system, any attempt to use this ABI on systems prior to SnowLeopard is undefined. - -1. High Level - -The ABI of blocks consist of their layout and the runtime functions required by the compiler. -A Block consists of a structure of the following form: - -struct Block_literal_1 { - void *isa; // initialized to &_NSConcreteStackBlock or &_NSConcreteGlobalBlock - int flags; - int reserved; - void (*invoke)(void *, ...); - struct Block_descriptor_1 { - unsigned long int reserved; // NULL - unsigned long int size; // sizeof(struct Block_literal_1) - // optional helper functions - void (*copy_helper)(void *dst, void *src); // IFF (1<<25) - void (*dispose_helper)(void *src); // IFF (1<<25) - // required ABI.2010.3.16 - const char *signature; // IFF (1<<30) - } *descriptor; - // imported variables -}; - -The following flags bits are in use thusly for a possible ABI.2010.3.16: - -enum { - BLOCK_HAS_COPY_DISPOSE = (1 << 25), - BLOCK_HAS_CTOR = (1 << 26), // helpers have C++ code - BLOCK_IS_GLOBAL = (1 << 28), - BLOCK_HAS_STRET = (1 << 29), // IFF BLOCK_HAS_SIGNATURE - BLOCK_HAS_SIGNATURE = (1 << 30), -}; - -In 10.6.ABI the (1<<29) was usually set and was always ignored by the runtime - it had been a transitional marker that did not get deleted after the transition. This bit is now paired with (1<<30), and represented as the pair (3<<30), for the following combinations of valid bit settings, and their meanings. - -switch (flags & (3<<29)) { - case (0<<29): 10.6.ABI, no signature field available - case (1<<29): 10.6.ABI, no signature field available - case (2<<29): ABI.2010.3.16, regular calling convention, presence of signature field - case (3<<29): ABI.2010.3.16, stret calling convention, presence of signature field, -} - -The signature field is not always populated. - -The following discussions are presented as 10.6.ABI otherwise. - -Block literals may occur within functions where the structure is created in stack local memory. They may also appear as initialization expressions for Block variables of global or static local variables. - -When a Block literal expression is evaluated the stack based structure is initialized as follows: - -1) static descriptor structure is declared and initialized as follows: -1a) the invoke function pointer is set to a function that takes the Block structure as its first argument and the rest of the arguments (if any) to the Block and executes the Block compound statement. -1b) the size field is set to the size of the following Block literal structure. -1c) the copy_helper and dispose_helper function pointers are set to respective helper functions if they are required by the Block literal -2) a stack (or global) Block literal data structure is created and initialized as follows: -2a) the isa field is set to the address of the external _NSConcreteStackBlock, which is a block of uninitialized memory supplied in libSystem, or _NSConcreteGlobalBlock if this is a static or file level block literal. -2) The flags field is set to zero unless there are variables imported into the block that need helper functions for program level Block_copy() and Block_release() operations, in which case the (1<<25) flags bit is set. - - -As an example, the Block literal expression - ^ { printf("hello world\n"); } -would cause to be created on a 32-bit system: - -struct __block_literal_1 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_1 *); - struct __block_descriptor_1 *descriptor; -}; - -void __block_invoke_1(struct __block_literal_1 *_block) { - printf("hello world\n"); -} - -static struct __block_descriptor_1 { - unsigned long int reserved; - unsigned long int Block_size; -} __block_descriptor_1 = { 0, sizeof(struct __block_literal_1), __block_invoke_1 }; - -and where the block literal appeared - - struct __block_literal_1 _block_literal = { - &_NSConcreteStackBlock, - (1<<29), , - __block_invoke_1, - &__block_descriptor_1 - }; - -Blocks import other Block references, const copies of other variables, and variables marked __block. In Objective-C variables may additionally be objects. - -When a Block literal expression used as the initial value of a global or static local variable it is initialized as follows: - struct __block_literal_1 __block_literal_1 = { - &_NSConcreteGlobalBlock, - (1<<28)|(1<<29), , - __block_invoke_1, - &__block_descriptor_1 - }; -that is, a different address is provided as the first value and a particular (1<<28) bit is set in the flags field, and otherwise it is the same as for stack based Block literals. This is an optimization that can be used for any Block literal that imports no const or __block storage variables. - - -2. Imported Variables - -Variables of "auto" storage class are imported as const copies. Variables of "__block" storage class are imported as a pointer to an enclosing data structure. Global variables are simply referenced and not considered as imported. - -2.1 Imported const copy variables - -Automatic storage variables not marked with __block are imported as const copies. - -The simplest example is that of importing a variable of type int. - - int x = 10; - void (^vv)(void) = ^{ printf("x is %d\n", x); } - x = 11; - vv(); - -would be compiled - -struct __block_literal_2 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_2 *); - struct __block_descriptor_2 *descriptor; - const int x; -}; - -void __block_invoke_2(struct __block_literal_2 *_block) { - printf("x is %d\n", _block->x); -} - -static struct __block_descriptor_2 { - unsigned long int reserved; - unsigned long int Block_size; -} __block_descriptor_2 = { 0, sizeof(struct __block_literal_2) }; - -and - - struct __block_literal_2 __block_literal_2 = { - &_NSConcreteStackBlock, - (1<<29), , - __block_invoke_2, - &__block_descriptor_2, - x - }; - -In summary, scalars, structures, unions, and function pointers are generally imported as const copies with no need for helper functions. - -2.2 Imported const copy of Block reference - -The first case where copy and dispose helper functions are required is for the case of when a block itself is imported. In this case both a copy_helper function and a dispose_helper function are needed. The copy_helper function is passed both the existing stack based pointer and the pointer to the new heap version and should call back into the runtime to actually do the copy operation on the imported fields within the block. The runtime functions are all described in Section 5.0 Runtime Helper Functions. - -An example: - - void (^existingBlock)(void) = ...; - void (^vv)(void) = ^{ existingBlock(); } - vv(); - -struct __block_literal_3 { - ...; // existing block -}; - -struct __block_literal_4 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_4 *); - struct __block_literal_3 *const existingBlock; -}; - -void __block_invoke_4(struct __block_literal_2 *_block) { - __block->existingBlock->invoke(__block->existingBlock); -} - -void __block_copy_4(struct __block_literal_4 *dst, struct __block_literal_4 *src) { - //_Block_copy_assign(&dst->existingBlock, src->existingBlock, 0); - _Block_object_assign(&dst->existingBlock, src->existingBlock, BLOCK_FIELD_IS_BLOCK); -} - -void __block_dispose_4(struct __block_literal_4 *src) { - // was _Block_destroy - _Block_object_dispose(src->existingBlock, BLOCK_FIELD_IS_BLOCK); -} - -static struct __block_descriptor_4 { - unsigned long int reserved; - unsigned long int Block_size; - void (*copy_helper)(struct __block_literal_4 *dst, struct __block_literal_4 *src); - void (*dispose_helper)(struct __block_literal_4 *); -} __block_descriptor_4 = { - 0, - sizeof(struct __block_literal_4), - __block_copy_4, - __block_dispose_4, -}; - -and where it is used - - struct __block_literal_4 _block_literal = { - &_NSConcreteStackBlock, - (1<<25)|(1<<29), - __block_invoke_4, - & __block_descriptor_4 - existingBlock, - }; - -2.2.1 Importing __attribute__((NSObject)) variables. - -GCC introduces __attribute__((NSObject)) on structure pointers to mean "this is an object". This is useful because many low level data structures are declared as opaque structure pointers, e.g. CFStringRef, CFArrayRef, etc. When used from C, however, these are still really objects and are the second case where that requires copy and dispose helper functions to be generated. The copy helper functions generated by the compiler should use the _Block_object_assign runtime helper function and in the dispose helper the _Block_object_dispose runtime helper function should be called. - -For example, block xyzzy in the following - - struct Opaque *__attribute__((NSObject)) objectPointer = ...; - ... - void (^xyzzy)(void) = ^{ CFPrint(objectPointer); }; - -would have helper functions - -void __block_copy_xyzzy(struct __block_literal_5 *dst, struct __block_literal_5 *src) { - _Block_object_assign(&dst->objectPointer, src-> objectPointer, BLOCK_FIELD_IS_OBJECT); -} - -void __block_dispose_xyzzy(struct __block_literal_5 *src) { - _Block_object_dispose(src->objectPointer, BLOCK_FIELD_IS_OBJECT); -} - -generated. - - -2.3 Imported __block marked variables. - -2.3.1 Layout of __block marked variables - -The compiler must embed variables that are marked __block in a specialized structure of the form: - -struct _block_byref_xxxx { - void *isa; - struct Block_byref *forwarding; - int flags; //refcount; - int size; - typeof(marked_variable) marked_variable; -}; - -Variables of certain types require helper functions for when Block_copy() and Block_release() are performed upon a referencing Block. At the "C" level only variables that are of type Block or ones that have __attribute__((NSObject)) marked require helper functions. In Objective-C objects require helper functions and in C++ stack based objects require helper functions. Variables that require helper functions use the form: - -struct _block_byref_xxxx { - void *isa; - struct _block_byref_xxxx *forwarding; - int flags; //refcount; - int size; - // helper functions called via Block_copy() and Block_release() - void (*byref_keep)(void *dst, void *src); - void (*byref_dispose)(void *); - typeof(marked_variable) marked_variable; -}; - -The structure is initialized such that - a) the forwarding pointer is set to the beginning of its enclosing structure, - b) the size field is initialized to the total size of the enclosing structure, - c) the flags field is set to either 0 if no helper functions are needed or (1<<25) if they are, - d) the helper functions are initialized (if present) - e) the variable itself is set to its initial value. - f) the isa field is set to NULL - -2.3.2 Access to __block variables from within its lexical scope. - -In order to "move" the variable to the heap upon a copy_helper operation the compiler must rewrite access to such a variable to be indirect through the structures forwarding pointer. For example: - - int __block i = 10; - i = 11; - -would be rewritten to be: - - struct _block_byref_i { - void *isa; - struct _block_byref_i *forwarding; - int flags; //refcount; - int size; - int captured_i; - } i = { NULL, &i, 0, sizeof(struct _block_byref_i), 10 }; - - i.forwarding->captured_i = 11; - -In the case of a Block reference variable being marked __block the helper code generated must use the _Block_object_assign and _Block_object_dispose routines supplied by the runtime to make the copies. For example: - - __block void (voidBlock)(void) = blockA; - voidBlock = blockB; - -would translate into - -struct _block_byref_voidBlock { - void *isa; - struct _block_byref_voidBlock *forwarding; - int flags; //refcount; - int size; - void (*byref_keep)(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src); - void (*byref_dispose)(struct _block_byref_voidBlock *); - void (^captured_voidBlock)(void); -}; - -void _block_byref_keep_helper(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) { - //_Block_copy_assign(&dst->captured_voidBlock, src->captured_voidBlock, 0); - _Block_object_assign(&dst->captured_voidBlock, src->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER); -} - -void _block_byref_dispose_helper(struct _block_byref_voidBlock *param) { - //_Block_destroy(param->captured_voidBlock, 0); - _Block_object_dispose(param->captured_voidBlock, BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER)} - -and - struct _block_byref_voidBlock voidBlock = {( .forwarding=&voidBlock, .flags=(1<<25), .size=sizeof(struct _block_byref_voidBlock *), - .byref_keep=_block_byref_keep_helper, .byref_dispose=_block_byref_dispose_helper, - .captured_voidBlock=blockA )}; - - voidBlock.forwarding->captured_voidBlock = blockB; - - -2.3.3 Importing __block variables into Blocks - -A Block that uses a __block variable in its compound statement body must import the variable and emit copy_helper and dispose_helper helper functions that, in turn, call back into the runtime to actually copy or release the byref data block using the functions _Block_object_assign and _Block_object_dispose. - -For example: - - int __block i = 2; - functioncall(^{ i = 10; }); - -would translate to - -struct _block_byref_i { - void *isa; // set to NULL - struct _block_byref_voidBlock *forwarding; - int flags; //refcount; - int size; - void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src); - void (*byref_dispose)(struct _block_byref_i *); - int captured_i; -}; - - -struct __block_literal_5 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_5 *); - struct __block_descriptor_5 *descriptor; - struct _block_byref_i *i_holder; -}; - -void __block_invoke_5(struct __block_literal_5 *_block) { - _block->forwarding->captured_i = 10; -} - -void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) { - //_Block_byref_assign_copy(&dst->captured_i, src->captured_i); - _Block_object_assign(&dst->captured_i, src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER); -} - -void __block_dispose_5(struct __block_literal_5 *src) { - //_Block_byref_release(src->captured_i); - _Block_object_dispose(src->captured_i, BLOCK_FIELD_IS_BYREF | BLOCK_BYREF_CALLER); -} - -static struct __block_descriptor_5 { - unsigned long int reserved; - unsigned long int Block_size; - void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src); - void (*dispose_helper)(struct __block_literal_5 *); -} __block_descriptor_5 = { 0, sizeof(struct __block_literal_5) __block_copy_5, __block_dispose_5 }; - -and - - struct _block_byref_i i = {( .forwarding=&i, .flags=0, .size=sizeof(struct _block_byref_i) )}; - struct __block_literal_5 _block_literal = { - &_NSConcreteStackBlock, - (1<<25)|(1<<29), , - __block_invoke_5, - &__block_descriptor_5, - 2, - }; - -2.3.4 Importing __attribute__((NSObject)) __block variables - -A __block variable that is also marked __attribute__((NSObject)) should have byref_keep and byref_dispose helper functions that use _Block_object_assign and _Block_object_dispose. - -2.3.5 __block escapes - -Because Blocks referencing __block variables may have Block_copy() performed upon them the underlying storage for the variables may move to the heap. In Objective-C Garbage Collection Only compilation environments the heap used is the garbage collected one and no further action is required. Otherwise the compiler must issue a call to potentially release any heap storage for __block variables at all escapes or terminations of their scope. The call should be: - - _Block_object_dispose(&_block_byref_xxx, BLOCK_FIELD_IS_BYREF); - - -2.3.6 Nesting - -Blocks may contain Block literal expressions. Any variables used within inner blocks are imported into all enclosing Block scopes even if the variables are not used. This includes const imports as well as __block variables. - -3. Objective C Extensions to Blocks - -3.1 Importing Objects - -Objects should be treated as __attribute__((NSObject)) variables; all copy_helper, dispose_helper, byref_keep, and byref_dispose helper functions should use _Block_object_assign and _Block_object_dispose. There should be no code generated that uses -retain or -release methods. - - -3.2 Blocks as Objects - -The compiler will treat Blocks as objects when synthesizing property setters and getters, will characterize them as objects when generating garbage collection strong and weak layout information in the same manner as objects, and will issue strong and weak write-barrier assignments in the same manner as objects. - -3.3 __weak __block Support - -Objective-C (and Objective-C++) support the __weak attribute on __block variables. Under normal circumstances the compiler uses the Objective-C runtime helper support functions objc_assign_weak and objc_read_weak. Both should continue to be used for all reads and writes of __weak __block variables: - objc_read_weak(&block->byref_i->forwarding->i) - -The __weak variable is stored in a _block_byref_xxxx structure and the Block has copy and dispose helpers for this structure that call: - _Block_object_assign(&dest->_block_byref_i, src-> _block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF); -and - _Block_object_dispose(src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BYREF); - - -In turn, the block_byref copy support helpers distinguish between whether the __block variable is a Block or not and should either call: - _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_OBJECT | BLOCK_BYREF_CALLER); -for something declared as an object or - _Block_object_assign(&dest->_block_byref_i, src->_block_byref_i, BLOCK_FIELD_IS_WEAK | BLOCK_FIELD_IS_BLOCK | BLOCK_BYREF_CALLER); -for something declared as a Block. - -A full example follows: - - - __block __weak id obj = ; - functioncall(^{ [obj somemessage]; }); - -would translate to - -struct _block_byref_obj { - void *isa; // uninitialized - struct _block_byref_obj *forwarding; - int flags; //refcount; - int size; - void (*byref_keep)(struct _block_byref_i *dst, struct _block_byref_i *src); - void (*byref_dispose)(struct _block_byref_i *); - id captured_obj; -}; - -void _block_byref_obj_keep(struct _block_byref_voidBlock *dst, struct _block_byref_voidBlock *src) { - //_Block_copy_assign(&dst->captured_obj, src->captured_obj, 0); - _Block_object_assign(&dst->captured_obj, src->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER); -} - -void _block_byref_obj_dispose(struct _block_byref_voidBlock *param) { - //_Block_destroy(param->captured_obj, 0); - _Block_object_dispose(param->captured_obj, BLOCK_FIELD_IS_OBJECT | BLOCK_FIELD_IS_WEAK | BLOCK_BYREF_CALLER); -}; - -for the block byref part and - -struct __block_literal_5 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_5 *); - struct __block_descriptor_5 *descriptor; - struct _block_byref_obj *byref_obj; -}; - -void __block_invoke_5(struct __block_literal_5 *_block) { - [objc_read_weak(&_block->byref_obj->forwarding->captured_obj) somemessage]; -} - -void __block_copy_5(struct __block_literal_5 *dst, struct __block_literal_5 *src) { - //_Block_byref_assign_copy(&dst->byref_obj, src->byref_obj); - _Block_object_assign(&dst->byref_obj, src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK); -} - -void __block_dispose_5(struct __block_literal_5 *src) { - //_Block_byref_release(src->byref_obj); - _Block_object_dispose(src->byref_obj, BLOCK_FIELD_IS_BYREF | BLOCK_FIELD_IS_WEAK); -} - -static struct __block_descriptor_5 { - unsigned long int reserved; - unsigned long int Block_size; - void (*copy_helper)(struct __block_literal_5 *dst, struct __block_literal_5 *src); - void (*dispose_helper)(struct __block_literal_5 *); -} __block_descriptor_5 = { 0, sizeof(struct __block_literal_5), __block_copy_5, __block_dispose_5 }; - -and within the compound statement: - - struct _block_byref_obj obj = {( .forwarding=&obj, .flags=(1<<25), .size=sizeof(struct _block_byref_obj), - .byref_keep=_block_byref_obj_keep, .byref_dispose=_block_byref_obj_dispose, - .captured_obj = )}; - - struct __block_literal_5 _block_literal = { - &_NSConcreteStackBlock, - (1<<25)|(1<<29), , - __block_invoke_5, - &__block_descriptor_5, - &obj, // a reference to the on-stack structure containing "captured_obj" - }; - - - functioncall(_block_literal->invoke(&_block_literal)); - - -4.0 C++ Support - -Within a block stack based C++ objects are copied into const copies using the copy constructor. It is an error if a stack based C++ object is used within a block if it does not have a copy constructor. In addition both copy and destroy helper routines must be synthesized for the block to support the Block_copy() operation, and the flags work marked with the (1<<26) bit in addition to the (1<<25) bit. The copy helper should call the constructor using appropriate offsets of the variable within the supplied stack based block source and heap based destination for all const constructed copies, and similarly should call the destructor in the destroy routine. - -As an example, suppose a C++ class FOO existed with a copy constructor. Within a code block a stack version of a FOO object is declared and used within a Block literal expression: - -{ - FOO foo; - void (^block)(void) = ^{ printf("%d\n", foo.value()); }; -} - -The compiler would synthesize - -struct __block_literal_10 { - void *isa; - int flags; - int reserved; - void (*invoke)(struct __block_literal_10 *); - struct __block_descriptor_10 *descriptor; - const FOO foo; -}; - -void __block_invoke_10(struct __block_literal_10 *_block) { - printf("%d\n", _block->foo.value()); -} - -void __block_literal_10(struct __block_literal_10 *dst, struct __block_literal_10 *src) { - FOO_ctor(&dst->foo, &src->foo); -} - -void __block_dispose_10(struct __block_literal_10 *src) { - FOO_dtor(&src->foo); -} - -static struct __block_descriptor_10 { - unsigned long int reserved; - unsigned long int Block_size; - void (*copy_helper)(struct __block_literal_10 *dst, struct __block_literal_10 *src); - void (*dispose_helper)(struct __block_literal_10 *); -} __block_descriptor_10 = { 0, sizeof(struct __block_literal_10), __block_copy_10, __block_dispose_10 }; - -and the code would be: -{ - FOO foo; - comp_ctor(&foo); // default constructor - struct __block_literal_10 _block_literal = { - &_NSConcreteStackBlock, - (1<<25)|(1<<26)|(1<<29), , - __block_invoke_10, - &__block_descriptor_10, - }; - comp_ctor(&_block_literal->foo, &foo); // const copy into stack version - struct __block_literal_10 &block = &_block_literal; // assign literal to block variable - block->invoke(block); // invoke block - comp_dtor(&_block_literal->foo); // destroy stack version of const block copy - comp_dtor(&foo); // destroy original version -} - - -C++ objects stored in __block storage start out on the stack in a block_byref data structure as do other variables. Such objects (if not const objects) must support a regular copy constructor. The block_byref data structure will have copy and destroy helper routines synthesized by the compiler. The copy helper will have code created to perform the copy constructor based on the initial stack block_byref data structure, and will also set the (1<<26) bit in addition to the (1<<25) bit. The destroy helper will have code to do the destructor on the object stored within the supplied block_byref heap data structure. For example, - - __block FOO blockStorageFoo; - -requires the normal constructor for the embedded blockStorageFoo object - - FOO_ctor(& _block_byref_blockStorageFoo->blockStorageFoo); - -and at scope termination the destructor: - - FOO_dtor(& _block_byref_blockStorageFoo->blockStorageFoo); - -Note that the forwarding indirection is NOT used. - -The compiler would need to generate (if used from a block literal) the following copy/dispose helpers: - -void _block_byref_obj_keep(struct _block_byref_blockStorageFoo *dst, struct _block_byref_blockStorageFoo *src) { - FOO_ctor(&dst->blockStorageFoo, &src->blockStorageFoo); -} - -void _block_byref_obj_dispose(struct _block_byref_blockStorageFoo *src) { - FOO_dtor(&src->blockStorageFoo); -} - -for the appropriately named constructor and destructor for the class/struct FOO. - -To support member variable and function access the compiler will synthesize a const pointer to a block version of the "this" pointer. - -5.0 Runtime Helper Functions - -The runtime helper functions are described in /usr/local/include/Block_private.h. To summarize their use, a block requires copy/dispose helpers if it imports any block variables, __block storage variables, __attribute__((NSObject)) variables, or C++ const copied objects with constructor/destructors. The (1<<26) bit is set and functions are generated. - -The block copy helper function should, for each of the variables of the type mentioned above, call - _Block_object_assign(&dst->target, src->target, BLOCK_FIELD_); -in the copy helper and - _Block_object_dispose(->target, BLOCK_FIELD_); -in the dispose helper where - is - -enum { - BLOCK_FIELD_IS_OBJECT = 3, // id, NSObject, __attribute__((NSObject)), block, ... - BLOCK_FIELD_IS_BLOCK = 7, // a block variable - BLOCK_FIELD_IS_BYREF = 8, // the on stack structure holding the __block variable - - BLOCK_FIELD_IS_WEAK = 16, // declared __weak - - BLOCK_BYREF_CALLER = 128, // called from byref copy/dispose helpers -}; - -and of course the CTORs/DTORs for const copied C++ objects. - -The block_byref data structure similarly requires copy/dispose helpers for block variables, __attribute__((NSObject)) variables, or C++ const copied objects with constructor/destructors, and again the (1<<26) bit is set and functions are generated in the same manner. - -Under ObjC we allow __weak as an attribute on __block variables, and this causes the addition of BLOCK_FIELD_IS_WEAK orred onto the BLOCK_FIELD_IS_BYREF flag when copying the block_byref structure in the block copy helper, and onto the BLOCK_FIELD_ field within the block_byref copy/dispose helper calls. - -The prototypes, and summary, of the helper functions are - -/* Certain field types require runtime assistance when being copied to the heap. The following function is used - to copy fields of types: blocks, pointers to byref structures, and objects (including __attribute__((NSObject)) pointers. - BLOCK_FIELD_IS_WEAK is orthogonal to the other choices which are mutually exclusive. - Only in a Block copy helper will one see BLOCK_FIELD_IS_BYREF. - */ -void _Block_object_assign(void *destAddr, const void *object, const int flags); - -/* Similarly a compiler generated dispose helper needs to call back for each field of the byref data structure. - (Currently the implementation only packs one field into the byref structure but in principle there could be more). - The same flags used in the copy helper should be used for each call generated to this function: - */ -void _Block_object_dispose(const void *object, const int flags); +*NOTE* This document has moved to http://clang.llvm.org/docs/Block-ABI-Apple.html. diff --git a/docs/BlockLanguageSpec.rst b/docs/BlockLanguageSpec.rst new file mode 100644 index 000000000000..3632d566838a --- /dev/null +++ b/docs/BlockLanguageSpec.rst @@ -0,0 +1,361 @@ + +.. role:: block-term + +================================= +Language Specification for Blocks +================================= + +.. contents:: + :local: + +Revisions +========= + +- 2008/2/25 --- created +- 2008/7/28 --- revised, ``__block`` syntax +- 2008/8/13 --- revised, Block globals +- 2008/8/21 --- revised, C++ elaboration +- 2008/11/1 --- revised, ``__weak`` support +- 2009/1/12 --- revised, explicit return types +- 2009/2/10 --- revised, ``__block`` objects need retain + +Overview +======== + +A new derived type is introduced to C and, by extension, Objective-C, +C++, and Objective-C++ + +The Block Type +============== + +Like function types, the :block-term:`Block type` is a pair consisting +of a result value type and a list of parameter types very similar to a +function type. Blocks are intended to be used much like functions with +the key distinction being that in addition to executable code they +also contain various variable bindings to automatic (stack) or managed +(heap) memory. + +The abstract declarator, + +.. code-block:: c + + int (^)(char, float) + +describes a reference to a Block that, when invoked, takes two +parameters, the first of type char and the second of type float, and +returns a value of type int. The Block referenced is of opaque data +that may reside in automatic (stack) memory, global memory, or heap +memory. + +Block Variable Declarations +=========================== + +A :block-term:`variable with Block type` is declared using function +pointer style notation substituting ``^`` for ``*``. The following are +valid Block variable declarations: + +.. code-block:: c + + void (^blockReturningVoidWithVoidArgument)(void); + int (^blockReturningIntWithIntAndCharArguments)(int, char); + void (^arrayOfTenBlocksReturningVoidWithIntArgument[10])(int); + +Variadic ``...`` arguments are supported. [variadic.c] A Block that +takes no arguments must specify void in the argument list [voidarg.c]. +An empty parameter list does not represent, as K&R provide, an +unspecified argument list. Note: both gcc and clang support K&R style +as a convenience. + +A Block reference may be cast to a pointer of arbitrary type and vice +versa. [cast.c] A Block reference may not be dereferenced via the +pointer dereference operator ``*``, and thus a Block's size may not be +computed at compile time. [sizeof.c] + +Block Literal Expressions +========================= + +A :block-term:`Block literal expression` produces a reference to a +Block. It is introduced by the use of the ``^`` token as a unary +operator. + +.. code-block:: c + + Block_literal_expression ::= ^ block_decl compound_statement_body + block_decl ::= + block_decl ::= parameter_list + block_decl ::= type_expression + +where type expression is extended to allow ``^`` as a Block reference +(pointer) where ``*`` is allowed as a function reference (pointer). + +The following Block literal: + +.. code-block:: c + + ^ void (void) { printf("hello world\n"); } + +produces a reference to a Block with no arguments with no return value. + +The return type is optional and is inferred from the return +statements. If the return statements return a value, they all must +return a value of the same type. If there is no value returned the +inferred type of the Block is void; otherwise it is the type of the +return statement value. + +If the return type is omitted and the argument list is ``( void )``, +the ``( void )`` argument list may also be omitted. + +So: + +.. code-block:: c + + ^ ( void ) { printf("hello world\n"); } + +and: + +.. code-block:: c + + ^ { printf("hello world\n"); } + +are exactly equivalent constructs for the same expression. + +The type_expression extends C expression parsing to accommodate Block +reference declarations as it accommodates function pointer +declarations. + +Given: + +.. code-block:: c + + typedef int (*pointerToFunctionThatReturnsIntWithCharArg)(char); + pointerToFunctionThatReturnsIntWithCharArg functionPointer; + ^ pointerToFunctionThatReturnsIntWithCharArg (float x) { return functionPointer; } + +and: + +.. code-block:: c + + ^ int ((*)(float x))(char) { return functionPointer; } + +are equivalent expressions, as is: + +.. code-block:: c + + ^(float x) { return functionPointer; } + +[returnfunctionptr.c] + +The compound statement body establishes a new lexical scope within +that of its parent. Variables used within the scope of the compound +statement are bound to the Block in the normal manner with the +exception of those in automatic (stack) storage. Thus one may access +functions and global variables as one would expect, as well as static +local variables. [testme] + +Local automatic (stack) variables referenced within the compound +statement of a Block are imported and captured by the Block as const +copies. The capture (binding) is performed at the time of the Block +literal expression evaluation. + +The compiler is not required to capture a variable if it can prove +that no references to the variable will actually be evaluated. +Programmers can force a variable to be captured by referencing it in a +statement at the beginning of the Block, like so: + +.. code-block:: c + + (void) foo; + +This matters when capturing the variable has side-effects, as it can +in Objective-C or C++. + +The lifetime of variables declared in a Block is that of a function; +each activation frame contains a new copy of variables declared within +the local scope of the Block. Such variable declarations should be +allowed anywhere [testme] rather than only when C99 parsing is +requested, including for statements. [testme] + +Block literal expressions may occur within Block literal expressions +(nest) and all variables captured by any nested blocks are implicitly +also captured in the scopes of their enclosing Blocks. + +A Block literal expression may be used as the initialization value for +Block variables at global or local static scope. + +The Invoke Operator +=================== + +Blocks are :block-term:`invoked` using function call syntax with a +list of expression parameters of types corresponding to the +declaration and returning a result type also according to the +declaration. Given: + +.. code-block:: c + + int (^x)(char); + void (^z)(void); + int (^(*y))(char) = &x; + +the following are all legal Block invocations: + +.. code-block:: c + + x('a'); + (*y)('a'); + (true ? x : *y)('a') + +The Copy and Release Operations +=============================== + +The compiler and runtime provide :block-term:`copy` and +:block-term:`release` operations for Block references that create and, +in matched use, release allocated storage for referenced Blocks. + +The copy operation ``Block_copy()`` is styled as a function that takes +an arbitrary Block reference and returns a Block reference of the same +type. The release operation, ``Block_release()``, is styled as a +function that takes an arbitrary Block reference and, if dynamically +matched to a Block copy operation, allows recovery of the referenced +allocated memory. + + +The ``__block`` Storage Qualifier +================================= + +In addition to the new Block type we also introduce a new storage +qualifier, :block-term:`__block`, for local variables. [testme: a +__block declaration within a block literal] The ``__block`` storage +qualifier is mutually exclusive to the existing local storage +qualifiers auto, register, and static. [testme] Variables qualified by +``__block`` act as if they were in allocated storage and this storage +is automatically recovered after last use of said variable. An +implementation may choose an optimization where the storage is +initially automatic and only "moved" to allocated (heap) storage upon +a Block_copy of a referencing Block. Such variables may be mutated as +normal variables are. + +In the case where a ``__block`` variable is a Block one must assume +that the ``__block`` variable resides in allocated storage and as such +is assumed to reference a Block that is also in allocated storage +(that it is the result of a ``Block_copy`` operation). Despite this +there is no provision to do a ``Block_copy`` or a ``Block_release`` if +an implementation provides initial automatic storage for Blocks. This +is due to the inherent race condition of potentially several threads +trying to update the shared variable and the need for synchronization +around disposing of older values and copying new ones. Such +synchronization is beyond the scope of this language specification. + + +Control Flow +============ + +The compound statement of a Block is treated much like a function body +with respect to control flow in that goto, break, and continue do not +escape the Block. Exceptions are treated *normally* in that when +thrown they pop stack frames until a catch clause is found. + + +Objective-C Extensions +====================== + +Objective-C extends the definition of a Block reference type to be +that also of id. A variable or expression of Block type may be +messaged or used as a parameter wherever an id may be. The converse is +also true. Block references may thus appear as properties and are +subject to the assign, retain, and copy attribute logic that is +reserved for objects. + +All Blocks are constructed to be Objective-C objects regardless of +whether the Objective-C runtime is operational in the program or +not. Blocks using automatic (stack) memory are objects and may be +messaged, although they may not be assigned into ``__weak`` locations +if garbage collection is enabled. + +Within a Block literal expression within a method definition +references to instance variables are also imported into the lexical +scope of the compound statement. These variables are implicitly +qualified as references from self, and so self is imported as a const +copy. The net effect is that instance variables can be mutated. + +The :block-term:`Block_copy` operator retains all objects held in +variables of automatic storage referenced within the Block expression +(or form strong references if running under garbage collection). +Object variables of ``__block`` storage type are assumed to hold +normal pointers with no provision for retain and release messages. + +Foundation defines (and supplies) ``-copy`` and ``-release`` methods for +Blocks. + +In the Objective-C and Objective-C++ languages, we allow the +``__weak`` specifier for ``__block`` variables of object type. If +garbage collection is not enabled, this qualifier causes these +variables to be kept without retain messages being sent. This +knowingly leads to dangling pointers if the Block (or a copy) outlives +the lifetime of this object. + +In garbage collected environments, the ``__weak`` variable is set to +nil when the object it references is collected, as long as the +``__block`` variable resides in the heap (either by default or via +``Block_copy()``). The initial Apple implementation does in fact +start ``__block`` variables on the stack and migrate them to the heap +only as a result of a ``Block_copy()`` operation. + +It is a runtime error to attempt to assign a reference to a +stack-based Block into any storage marked ``__weak``, including +``__weak`` ``__block`` variables. + + +C++ Extensions +============== + +Block literal expressions within functions are extended to allow const +use of C++ objects, pointers, or references held in automatic storage. + +As usual, within the block, references to captured variables become +const-qualified, as if they were references to members of a const +object. Note that this does not change the type of a variable of +reference type. + +For example, given a class Foo: + +.. code-block:: c + + Foo foo; + Foo &fooRef = foo; + Foo *fooPtr = &foo; + +A Block that referenced these variables would import the variables as +const variations: + +.. code-block:: c + + const Foo block_foo = foo; + Foo &block_fooRef = fooRef; + Foo *const block_fooPtr = fooPtr; + +Captured variables are copied into the Block at the instant of +evaluating the Block literal expression. They are also copied when +calling ``Block_copy()`` on a Block allocated on the stack. In both +cases, they are copied as if the variable were const-qualified, and +it's an error if there's no such constructor. + +Captured variables in Blocks on the stack are destroyed when control +leaves the compound statement that contains the Block literal +expression. Captured variables in Blocks on the heap are destroyed +when the reference count of the Block drops to zero. + +Variables declared as residing in ``__block`` storage may be initially +allocated in the heap or may first appear on the stack and be copied +to the heap as a result of a ``Block_copy()`` operation. When copied +from the stack, ``__block`` variables are copied using their normal +qualification (i.e. without adding const). In C++11, ``__block`` +variables are copied as x-values if that is possible, then as l-values +if not; if both fail, it's an error. The destructor for any initial +stack-based version is called at the variable's normal end of scope. + +References to ``this``, as well as references to non-static members of +any enclosing class, are evaluated by capturing ``this`` just like a +normal variable of C pointer type. + +Member variables that are Blocks may not be overloaded by the types of +their arguments. diff --git a/docs/BlockLanguageSpec.txt b/docs/BlockLanguageSpec.txt deleted file mode 100644 index 4cdf75a27871..000000000000 --- a/docs/BlockLanguageSpec.txt +++ /dev/null @@ -1,171 +0,0 @@ -Language Specification for Blocks - -2008/2/25 — created -2008/7/28 — revised, __block syntax -2008/8/13 — revised, Block globals -2008/8/21 — revised, C++ elaboration -2008/11/1 — revised, __weak support -2009/1/12 — revised, explicit return types -2009/2/10 — revised, __block objects need retain - -Copyright 2008-2009 Apple, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -The Block Type - -A new derived type is introduced to C and, by extension, Objective-C, C++, and Objective-C++. Like function types, the Block type is a pair consisting of a result value type and a list of parameter types very similar to a function type. Blocks are intended to be used much like functions with the key distinction being that in addition to executable code they also contain various variable bindings to automatic (stack) or managed (heap) memory. - -The abstract declarator int (^)(char, float) describes a reference to a Block that, when invoked, takes two parameters, the first of type char and the second of type float, and returns a value of type int. The Block referenced is of opaque data that may reside in automatic (stack) memory, global memory, or heap memory. - - -Block Variable Declarations - -A variable with Block type is declared using function pointer style notation substituting ^ for *. The following are valid Block variable declarations: - void (^blockReturningVoidWithVoidArgument)(void); - int (^blockReturningIntWithIntAndCharArguments)(int, char); - void (^arrayOfTenBlocksReturningVoidWithIntArgument[10])(int); - -Variadic ... arguments are supported. [variadic.c] A Block that takes no arguments must specify void in the argument list [voidarg.c]. An empty parameter list does not represent, as K&R provide, an unspecified argument list. Note: both gcc and clang support K&R style as a convenience. - -A Block reference may be cast to a pointer of arbitrary type and vice versa. [cast.c] A Block reference may not be dereferenced via the pointer dereference operator *, and thus a Block's size may not be computed at compile time. [sizeof.c] - - -Block Literal Expressions - -A Block literal expression produces a reference to a Block. It is introduced by the use of the ^ token as a unary operator. - Block_literal_expression ::= ^ block_decl compound_statement_body - block_decl ::= - block_decl ::= parameter_list - block_decl ::= type_expression - -...where type expression is extended to allow ^ as a Block reference (pointer) where * is allowed as a function reference (pointer). - -The following Block literal: - ^ void (void) { printf("hello world\n"); } - -...produces a reference to a Block with no arguments with no return value. - -The return type is optional and is inferred from the return statements. If the return statements return a value, they all must return a value of the same type. If there is no value returned the inferred type of the Block is void; otherwise it is the type of the return statement value. - -If the return type is omitted and the argument list is ( void ), the ( void ) argument list may also be omitted. - -So: - ^ ( void ) { printf("hello world\n"); } - -...and: - ^ { printf("hello world\n"); } - -...are exactly equivalent constructs for the same expression. - -The type_expression extends C expression parsing to accommodate Block reference declarations as it accommodates function pointer declarations. - -Given: - typedef int (*pointerToFunctionThatReturnsIntWithCharArg)(char); - pointerToFunctionThatReturnsIntWithCharArg functionPointer; - - ^ pointerToFunctionThatReturnsIntWithCharArg (float x) { return functionPointer; } - -...and: - ^ int ((*)(float x))(char) { return functionPointer; } - -...are equivalent expressions, as is: - - ^(float x) { return functionPointer; } - -[returnfunctionptr.c] - -The compound statement body establishes a new lexical scope within that of its parent. Variables used within the scope of the compound statement are bound to the Block in the normal manner with the exception of those in automatic (stack) storage. Thus one may access functions and global variables as one would expect, as well as static local variables. [testme] - -Local automatic (stack) variables referenced within the compound statement of a Block are imported and captured by the Block as const copies. The capture (binding) is performed at the time of the Block literal expression evaluation. - -The compiler is not required to capture a variable if it can prove that no references to the variable will actually be evaluated. Programmers can force a variable to be captured by referencing it in a statement at the beginning of the Block, like so: - (void) foo; -This matters when capturing the variable has side-effects, as it can in Objective-C or C++. - -The lifetime of variables declared in a Block is that of a function; each activation frame contains a new copy of variables declared within the local scope of the Block. Such variable declarations should be allowed anywhere [testme] rather than only when C99 parsing is requested, including for statements. [testme] - -Block literal expressions may occur within Block literal expressions (nest) and all variables captured by any nested blocks are implicitly also captured in the scopes of their enclosing Blocks. - -A Block literal expression may be used as the initialization value for Block variables at global or local static scope. - - -The Invoke Operator - -Blocks are invoked using function call syntax with a list of expression parameters of types corresponding to the declaration and returning a result type also according to the declaration. Given: - int (^x)(char); - void (^z)(void); - int (^(*y))(char) = &x; - -...the following are all legal Block invocations: - x('a'); - (*y)('a'); - (true ? x : *y)('a') - - -The Copy and Release Operations - -The compiler and runtime provide copy and release operations for Block references that create and, in matched use, release allocated storage for referenced Blocks. - -The copy operation Block_copy() is styled as a function that takes an arbitrary Block reference and returns a Block reference of the same type. The release operation, Block_release(), is styled as a function that takes an arbitrary Block reference and, if dynamically matched to a Block copy operation, allows recovery of the referenced allocated memory. - - -The __block Storage Qualifier - -In addition to the new Block type we also introduce a new storage qualifier, __block, for local variables. [testme: a __block declaration within a block literal] The __block storage qualifier is mutually exclusive to the existing local storage qualifiers auto, register, and static.[testme] Variables qualified by __block act as if they were in allocated storage and this storage is automatically recovered after last use of said variable. An implementation may choose an optimization where the storage is initially automatic and only "moved" to allocated (heap) storage upon a Block_copy of a referencing Block. Such variables may be mutated as normal variables are. - -In the case where a __block variable is a Block one must assume that the __block variable resides in allocated storage and as such is assumed to reference a Block that is also in allocated storage (that it is the result of a Block_copy operation). Despite this there is no provision to do a Block_copy or a Block_release if an implementation provides initial automatic storage for Blocks. This is due to the inherent race condition of potentially several threads trying to update the shared variable and the need for synchronization around disposing of older values and copying new ones. Such synchronization is beyond the scope of this language specification. - - -Control Flow - -The compound statement of a Block is treated much like a function body with respect to control flow in that goto, break, and continue do not escape the Block. Exceptions are treated "normally" in that when thrown they pop stack frames until a catch clause is found. - - -Objective-C Extensions - -Objective-C extends the definition of a Block reference type to be that also of id. A variable or expression of Block type may be messaged or used as a parameter wherever an id may be. The converse is also true. Block references may thus appear as properties and are subject to the assign, retain, and copy attribute logic that is reserved for objects. - -All Blocks are constructed to be Objective-C objects regardless of whether the Objective-C runtime is operational in the program or not. Blocks using automatic (stack) memory are objects and may be messaged, although they may not be assigned into __weak locations if garbage collection is enabled. - -Within a Block literal expression within a method definition references to instance variables are also imported into the lexical scope of the compound statement. These variables are implicitly qualified as references from self, and so self is imported as a const copy. The net effect is that instance variables can be mutated. - -The Block_copy operator retains all objects held in variables of automatic storage referenced within the Block expression (or form strong references if running under garbage collection). Object variables of __block storage type are assumed to hold normal pointers with no provision for retain and release messages. - -Foundation defines (and supplies) -copy and -release methods for Blocks. - -In the Objective-C and Objective-C++ languages, we allow the __weak specifier for __block variables of object type. If garbage collection is not enabled, this qualifier causes these variables to be kept without retain messages being sent. This knowingly leads to dangling pointers if the Block (or a copy) outlives the lifetime of this object. - -In garbage collected environments, the __weak variable is set to nil when the object it references is collected, as long as the __block variable resides in the heap (either by default or via Block_copy()). The initial Apple implementation does in fact start __block variables on the stack and migrate them to the heap only as a result of a Block_copy() operation. - -It is a runtime error to attempt to assign a reference to a stack-based Block into any storage marked __weak, including __weak __block variables. - - -C++ Extensions - -Block literal expressions within functions are extended to allow const use of C++ objects, pointers, or references held in automatic storage. - -As usual, within the block, references to captured variables become const-qualified, as if they were references to members of a const object. Note that this does not change the type of a variable of reference type. - -For example, given a class Foo: - Foo foo; - Foo &fooRef = foo; - Foo *fooPtr = &foo; - -A Block that referenced these variables would import the variables as const variations: - const Foo block_foo = foo; - Foo &block_fooRef = fooRef; - Foo *const block_fooPtr = fooPtr; - -Captured variables are copied into the Block at the instant of evaluating the Block literal expression. They are also copied when calling Block_copy() on a Block allocated on the stack. In both cases, they are copied as if the variable were const-qualified, and it's an error if there's no such constructor. - -Captured variables in Blocks on the stack are destroyed when control leaves the compound statement that contains the Block literal expression. Captured variables in Blocks on the heap are destroyed when the reference count of the Block drops to zero. - -Variables declared as residing in __block storage may be initially allocated in the heap or may first appear on the stack and be copied to the heap as a result of a Block_copy() operation. When copied from the stack, __block variables are copied using their normal qualification (i.e. without adding const). In C++11, __block variables are copied as x-values if that is possible, then as l-values if not; if both fail, it's an error. The destructor for any initial stack-based version is called at the variable's normal end of scope. - -References to 'this', as well as references to non-static members of any enclosing class, are evaluated by capturing 'this' just like a normal variable of C pointer type. - -Member variables that are Blocks may not be overloaded by the types of their arguments. - diff --git a/docs/ClangCheck.rst b/docs/ClangCheck.rst new file mode 100644 index 000000000000..4650049b1fbf --- /dev/null +++ b/docs/ClangCheck.rst @@ -0,0 +1,36 @@ +========== +ClangCheck +========== + +`ClangCheck` is a small wrapper around :doc:`LibTooling` which can be used to +do basic error checking and AST dumping. + +.. code-block:: console + + $ cat < snippet.cc + > void f() { + > int a = 0 + > } + > EOF + $ ~/clang/build/bin/clang-check snippet.cc -ast-dump -- + Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc. + /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of + declaration + int a = 0 + ^ + ; + (TranslationUnitDecl 0x7ff3a3029ed0 <> + (TypedefDecl 0x7ff3a302a410 <> __int128_t '__int128') + (TypedefDecl 0x7ff3a302a470 <> __uint128_t 'unsigned __int128') + (TypedefDecl 0x7ff3a302a830 <> __builtin_va_list '__va_list_tag [1]') + (FunctionDecl 0x7ff3a302a8d0 f 'void (void)' + (CompoundStmt 0x7ff3a302aa10 + (DeclStmt 0x7ff3a302a9f8 + (VarDecl 0x7ff3a302a980 a 'int' + (IntegerLiteral 0x7ff3a302a9d8 'int' 0)))))) + 1 error generated. + Error while processing snippet.cc. + +The '--' at the end is important as it prevents `clang-check` from search for a +compilation database. For more information on how to setup and use `clang-check` +in a project, see :doc:`HowToSetupToolingForLLVM`. diff --git a/docs/ClangFormat.rst b/docs/ClangFormat.rst new file mode 100644 index 000000000000..92d7fc319e10 --- /dev/null +++ b/docs/ClangFormat.rst @@ -0,0 +1,93 @@ +=========== +ClangFormat +=========== + +`ClangFormat` describes a set of tools that are built on top of +:doc:`LibFormat`. It can support your workflow in a variety of ways including a +standalone tool and editor integrations. + + +Standalone Tool +=============== + +:program:`clang-format` is located in `clang/tools/clang-format` and can be used +to format C/C++/Obj-C code. + +.. code-block:: console + + $ clang-format --help + OVERVIEW: A tool to format C/C++/Obj-C code. + + Currently supports LLVM and Google style guides. + If no arguments are specified, it formats the code from standard input + and writes the result to the standard output. + If is given, it reformats the file. If -i is specified together + with , the file is edited in-place. Otherwise, the result is + written to the standard output. + + USAGE: clang-format [options] [] + + OPTIONS: + -fatal-assembler-warnings - Consider warnings as error + -help - Display available options (-help-hidden for more) + -i - Inplace edit , if specified. + -length= - Format a range of this length, -1 for end of file. + -offset= - Format a range starting at this file offset. + -stats - Enable statistics output from program + -style= - Coding style, currently supports: LLVM, Google, Chromium. + -version - Display the version of this program + + +Vim Integration +=============== + +There is an integration for :program:`vim` which lets you run the +:program:`clang-format` standalone tool on your current buffer, optionally +selecting regions to reformat. The integration has the form of a `python`-file +which can be found under `clang/tools/clang-format/clang-format.py`. + +This can be integrated by adding the following to your `.vimrc`: + +.. code-block:: vim + + map :pyf /clang-format.py + imap :pyf /clang-format.pyi + +The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the +second line adds support for INSERT mode. Change "C-K" to another binding if +you need :program:`clang-format` on a different key (C-K stands for Ctrl+k). + +With this integration you can press the bound key and clang-format will +format the current line in NORMAL and INSERT mode or the selected region in +VISUAL mode. The line or region is extended to the next bigger syntactic +entity. + +It operates on the current, potentially unsaved buffer and does not create +or save any files. To revert a formatting, just undo. + + +Script for patch reformatting +============================= + +The python script `clang/tools/clang-format-diff.py` parses the output of +a unified diff and reformats all contained lines with :program:`clang-format`. + +.. code-block:: console + + usage: clang-format-diff.py [-h] [-p P] [-style STYLE] + + Reformat changed lines in diff + + optional arguments: + -h, --help show this help message and exit + -p P strip the smallest prefix containing P slashes + -style STYLE formatting style to apply (LLVM, Google) + +So to reformat all the lines in the latest :program:`git` commit, just do: + +.. code-block:: console + + git diff -U0 HEAD^ | clang-format-diff.py + +The :option:`-U0` will create a diff without context lines (the script would format +those as well). diff --git a/docs/ClangPlugins.html b/docs/ClangPlugins.html deleted file mode 100644 index ed560fe840ba..000000000000 --- a/docs/ClangPlugins.html +++ /dev/null @@ -1,170 +0,0 @@ - - - -Clang Plugins - - - - - - - -
- -

Clang Plugins

-

Clang Plugins make it possible to run extra user defined actions during -a compilation. This document will provide a basic walkthrough of how to write -and run a Clang Plugin.

- - -

Introduction

- - -

Clang Plugins run FrontendActions over code. See the -FrontendAction tutorial on how to write a -FrontendAction using the RecursiveASTVisitor. In this tutorial, we'll -demonstrate how to write a simple clang plugin. -

- - -

Writing a PluginASTAction

- - -

The main difference from writing normal FrontendActions is that you can -handle plugin command line options. The -PluginASTAction base class declares a ParseArgs method which you have to -implement in your plugin. -

-
-  bool ParseArgs(const CompilerInstance &CI,
-                 const std::vector<std::string>& args) {
-    for (unsigned i = 0, e = args.size(); i != e; ++i) {
-      if (args[i] == "-some-arg") {
-        // Handle the command line argument.
-      }
-    }
-    return true;
-  }
-
- - -

Registering a plugin

- - -

A plugin is loaded from a dynamic library at runtime by the compiler. To register -a plugin in a library, use FrontendPluginRegistry::Add:

-
-  static FrontendPluginRegistry::Add<MyPlugin> X("my-plugin-name", "my plugin description");
-
- - -

Putting it all together

- - -

Let's look at an example plugin that prints top-level function names. -This example is also checked into the clang repository; please also take a look -at the latest checked in version of PrintFunctionNames.cpp.

-
-#include "clang/Frontend/FrontendPluginRegistry.h"
-#include "clang/AST/ASTConsumer.h"
-#include "clang/AST/AST.h"
-#include "clang/Frontend/CompilerInstance.h"
-#include "llvm/Support/raw_ostream.h"
-using namespace clang;
-
-namespace {
-
-class PrintFunctionsConsumer : public ASTConsumer {
-public:
-  virtual bool HandleTopLevelDecl(DeclGroupRef DG) {
-    for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) {
-      const Decl *D = *i;
-      if (const NamedDecl *ND = dyn_cast<NamedDecl>(D))
-        llvm::errs() << "top-level-decl: \"" << ND->getNameAsString() << "\"\n";
-    }
-
-    return true;
-  }
-};
-
-class PrintFunctionNamesAction : public PluginASTAction {
-protected:
-  ASTConsumer *CreateASTConsumer(CompilerInstance &CI, llvm::StringRef) {
-    return new PrintFunctionsConsumer();
-  }
-
-  bool ParseArgs(const CompilerInstance &CI,
-                 const std::vector<std::string>& args) {
-    for (unsigned i = 0, e = args.size(); i != e; ++i) {
-      llvm::errs() << "PrintFunctionNames arg = " << args[i] << "\n";
-
-      // Example error handling.
-      if (args[i] == "-an-error") {
-        DiagnosticsEngine &D = CI.getDiagnostics();
-        unsigned DiagID = D.getCustomDiagID(
-          DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'");
-        D.Report(DiagID);
-        return false;
-      }
-    }
-    if (args.size() && args[0] == "help")
-      PrintHelp(llvm::errs());
-
-    return true;
-  }
-  void PrintHelp(llvm::raw_ostream& ros) {
-    ros << "Help for PrintFunctionNames plugin goes here\n";
-  }
-
-};
-
-}
-
-static FrontendPluginRegistry::Add<PrintFunctionNamesAction>
-X("print-fns", "print function names");
-
- - -

Running the plugin

- - -

To run a plugin, the dynamic library containing the plugin registry must be -loaded via the -load command line option. This will load all plugins that are -registered, and you can select the plugins to run by specifying the -plugin -option. Additional parameters for the plugins can be passed with -plugin-arg-<plugin-name>.

- -

Note that those options must reach clang's cc1 process. There are two -ways to do so:

-
    -
  • -Directly call the parsing process by using the -cc1 option; this has the -downside of not configuring the default header search paths, so you'll need to -specify the full system path configuration on the command line. -
    • -
  • -Use clang as usual, but prefix all arguments to the cc1 process with -Xclang. -
    • -
-

For example, to run the print-function-names plugin over a source file in clang, -first build the plugin, and then call clang with the plugin from the source tree:

-
-  $ export BD=/path/to/build/directory
-  $ (cd $BD && make PrintFunctionNames )
-  $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \
-        -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \
-        -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \
-        tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \
-        -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \
-        -plugin -Xclang print-fns
-
- -

Also see the print-function-name plugin example's -README

- - - -
- - - diff --git a/docs/ClangPlugins.rst b/docs/ClangPlugins.rst new file mode 100644 index 000000000000..7c5c65ccf1d4 --- /dev/null +++ b/docs/ClangPlugins.rst @@ -0,0 +1,150 @@ +============= +Clang Plugins +============= + +Clang Plugins make it possible to run extra user defined actions during a +compilation. This document will provide a basic walkthrough of how to write and +run a Clang Plugin. + +Introduction +============ + +Clang Plugins run FrontendActions over code. See the :doc:`FrontendAction +tutorial ` on how to write a ``FrontendAction`` using the +``RecursiveASTVisitor``. In this tutorial, we'll demonstrate how to write a +simple clang plugin. + +Writing a ``PluginASTAction`` +============================= + +The main difference from writing normal ``FrontendActions`` is that you can +handle plugin command line options. The ``PluginASTAction`` base class declares +a ``ParseArgs`` method which you have to implement in your plugin. + +.. code-block:: c++ + + bool ParseArgs(const CompilerInstance &CI, + const std::vector& args) { + for (unsigned i = 0, e = args.size(); i != e; ++i) { + if (args[i] == "-some-arg") { + // Handle the command line argument. + } + } + return true; + } + +Registering a plugin +==================== + +A plugin is loaded from a dynamic library at runtime by the compiler. To +register a plugin in a library, use ``FrontendPluginRegistry::Add<>``: + +.. code-block:: c++ + + static FrontendPluginRegistry::Add X("my-plugin-name", "my plugin description"); + +Putting it all together +======================= + +Let's look at an example plugin that prints top-level function names. This +example is also checked into the clang repository; please also take a look at +the latest `checked in version of PrintFunctionNames.cpp +`_. + +.. code-block:: c++ + + #include "clang/Frontend/FrontendPluginRegistry.h" + #include "clang/AST/ASTConsumer.h" + #include "clang/AST/AST.h" + #include "clang/Frontend/CompilerInstance.h" + #include "llvm/Support/raw_ostream.h" + using namespace clang; + + namespace { + + class PrintFunctionsConsumer : public ASTConsumer { + public: + virtual bool HandleTopLevelDecl(DeclGroupRef DG) { + for (DeclGroupRef::iterator i = DG.begin(), e = DG.end(); i != e; ++i) { + const Decl *D = *i; + if (const NamedDecl *ND = dyn_cast(D)) + llvm::errs() << "top-level-decl: \"" << ND->getNameAsString() << "\"\n"; + } + + return true; + } + }; + + class PrintFunctionNamesAction : public PluginASTAction { + protected: + ASTConsumer *CreateASTConsumer(CompilerInstance &CI, llvm::StringRef) { + return new PrintFunctionsConsumer(); + } + + bool ParseArgs(const CompilerInstance &CI, + const std::vector& args) { + for (unsigned i = 0, e = args.size(); i != e; ++i) { + llvm::errs() << "PrintFunctionNames arg = " << args[i] << "\n"; + + // Example error handling. + if (args[i] == "-an-error") { + DiagnosticsEngine &D = CI.getDiagnostics(); + unsigned DiagID = D.getCustomDiagID( + DiagnosticsEngine::Error, "invalid argument '" + args[i] + "'"); + D.Report(DiagID); + return false; + } + } + if (args.size() && args[0] == "help") + PrintHelp(llvm::errs()); + + return true; + } + void PrintHelp(llvm::raw_ostream& ros) { + ros << "Help for PrintFunctionNames plugin goes here\n"; + } + + }; + + } + + static FrontendPluginRegistry::Add + X("print-fns", "print function names"); + +Running the plugin +================== + +To run a plugin, the dynamic library containing the plugin registry must be +loaded via the :option:`-load` command line option. This will load all plugins +that are registered, and you can select the plugins to run by specifying the +:option:`-plugin` option. Additional parameters for the plugins can be passed with +:option:`-plugin-arg-`. + +Note that those options must reach clang's cc1 process. There are two +ways to do so: + +* Directly call the parsing process by using the :option:`-cc1` option; this + has the downside of not configuring the default header search paths, so + you'll need to specify the full system path configuration on the command + line. +* Use clang as usual, but prefix all arguments to the cc1 process with + :option:`-Xclang`. + +For example, to run the ``print-function-names`` plugin over a source file in +clang, first build the plugin, and then call clang with the plugin from the +source tree: + +.. code-block:: console + + $ export BD=/path/to/build/directory + $ (cd $BD && make PrintFunctionNames ) + $ clang++ -D_GNU_SOURCE -D_DEBUG -D__STDC_CONSTANT_MACROS \ + -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -D_GNU_SOURCE \ + -I$BD/tools/clang/include -Itools/clang/include -I$BD/include -Iinclude \ + tools/clang/tools/clang-check/ClangCheck.cpp -fsyntax-only \ + -Xclang -load -Xclang $BD/lib/PrintFunctionNames.so -Xclang \ + -plugin -Xclang print-fns + +Also see the print-function-name plugin example's +`README `_ + diff --git a/docs/ClangTools.html b/docs/ClangTools.html deleted file mode 100644 index 4de57bd2185d..000000000000 --- a/docs/ClangTools.html +++ /dev/null @@ -1,110 +0,0 @@ - - - -Clang Tools - - - - - - - -
- -

Clang Tools

-

Clang Tools are standalone command line (and potentially GUI) tools design -for use by C++ developers who are already using and enjoying Clang as their -compiler. These tools provide developer-oriented functionality such as fast -syntax checking, automatic formatting, refactoring, etc.

- -

Only a couple of the most basic and fundamental tools are kept in the primary -Clang Subversion project. The rest of the tools are kept in a side-project so -that developers who don't want or need to build them don't. If you want to get -access to the extra Clang Tools repository, simply check it out into the tools -tree of your Clang checkout and follow the usual process for building and -working with a combined LLVM/Clang checkout:

-
    -
  • With Subversion: -
      -
    • cd llvm/tools/clang/tools
      • -
    • svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk - extra
      • -
    -
    • -
  • Or with Git: -
      -
    • cd llvm/tools/clang/tools
      • -
    • git clone http://llvm.org/git/clang-tools-extra.git extra
      • -
    -
    • -
- -

This document describes a high-level overview of the organization of Clang -Tools within the project as well as giving an introduction to some of the more -important tools. However, it should be noted that this document is currently -focused on Clang and Clang Tool developers, not on end users of these tools.

- - -

Clang Tools Organization

- - -

Clang Tools are CLI or GUI programs that are intended to be directly used by -C++ developers. That is they are not primarily for use by Clang -developers, although they are hopefully useful to C++ developers who happen to -work on Clang, and we try to actively dogfood their functionality. They are -developed in three components: the underlying infrastructure for building -a standalone tool based on Clang, core shared logic used by many different tools -in the form of refactoring and rewriting libraries, and the tools -themselves.

- -

The underlying infrastructure for Clang Tools is the -LibTooling platform. See its documentation for -much more detailed information about how this infrastructure works. The common -refactoring and rewriting toolkit-style library is also part of LibTooling -organizationally.

- -

A few Clang Tools are developed along side the core Clang libraries as -examples and test cases of fundamental functionality. However, most of the tools -are developed in a side repository to provide easy separation from the core -libraries. We intentionally do not support public libraries in the side -repository, as we want to carefully review and find good APIs for libraries as -they are lifted out of a few tools and into the core Clang library set.

- -

Regardless of which repository Clang Tools' code resides in, the development -process and practices for all Clang Tools are exactly those of Clang itself. -They are entirely within the Clang project, regardless of the version -control scheme.

- - - -

Core Clang Tools

- - -

The core set of Clang tools that are within the main repository are tools -that very specifically compliment, and allow use and testing of Clang -specific functionality.

- -

clang-check

-

This tool combines the LibTooling framework for running a Clang tool with the -basic Clang diagnostics by syntax checking specific files in a fast, command -line interface. It can also accept flags to re-display the diagnostics in -different formats with different flags, suitable for use driving an IDE or -editor. Furthermore, it can be used in fixit-mode to directly apply fixit-hints -offered by clang.

- -

FIXME: Link to user-oriented clang-check documentation.

- - -

Extra Clang Tools

- - -

As various categories of Clang Tools are added to the extra repository, -they'll be tracked here. The focus of this documentation is on the scope and -features of the tools for other tool developers; each tool should provide its -own user-focused documentation.

- -
- - - diff --git a/docs/ClangTools.rst b/docs/ClangTools.rst new file mode 100644 index 000000000000..b7f7c7b0462f --- /dev/null +++ b/docs/ClangTools.rst @@ -0,0 +1,152 @@ +======== +Overview +======== + +Clang Tools are standalone command line (and potentially GUI) tools +designed for use by C++ developers who are already using and enjoying +Clang as their compiler. These tools provide developer-oriented +functionality such as fast syntax checking, automatic formatting, +refactoring, etc. + +Only a couple of the most basic and fundamental tools are kept in the +primary Clang Subversion project. The rest of the tools are kept in a +side-project so that developers who don't want or need to build them +don't. If you want to get access to the extra Clang Tools repository, +simply check it out into the tools tree of your Clang checkout and +follow the usual process for building and working with a combined +LLVM/Clang checkout: + +- With Subversion: + + - ``cd llvm/tools/clang/tools`` + - ``svn co http://llvm.org/svn/llvm-project/clang-tools-extra/trunk extra`` + +- Or with Git: + + - ``cd llvm/tools/clang/tools`` + - ``git clone http://llvm.org/git/clang-tools-extra.git extra`` + +This document describes a high-level overview of the organization of +Clang Tools within the project as well as giving an introduction to some +of the more important tools. However, it should be noted that this +document is currently focused on Clang and Clang Tool developers, not on +end users of these tools. + +Clang Tools Organization +======================== + +Clang Tools are CLI or GUI programs that are intended to be directly +used by C++ developers. That is they are *not* primarily for use by +Clang developers, although they are hopefully useful to C++ developers +who happen to work on Clang, and we try to actively dogfood their +functionality. They are developed in three components: the underlying +infrastructure for building a standalone tool based on Clang, core +shared logic used by many different tools in the form of refactoring and +rewriting libraries, and the tools themselves. + +The underlying infrastructure for Clang Tools is the +:doc:`LibTooling ` platform. See its documentation for much +more detailed information about how this infrastructure works. The +common refactoring and rewriting toolkit-style library is also part of +LibTooling organizationally. + +A few Clang Tools are developed along side the core Clang libraries as +examples and test cases of fundamental functionality. However, most of +the tools are developed in a side repository to provide easy separation +from the core libraries. We intentionally do not support public +libraries in the side repository, as we want to carefully review and +find good APIs for libraries as they are lifted out of a few tools and +into the core Clang library set. + +Regardless of which repository Clang Tools' code resides in, the +development process and practices for all Clang Tools are exactly those +of Clang itself. They are entirely within the Clang *project*, +regardless of the version control scheme. + +Core Clang Tools +================ + +The core set of Clang tools that are within the main repository are +tools that very specifically complement, and allow use and testing of +*Clang* specific functionality. + +``clang-check`` +--------------- + +:doc:`ClangCheck` combines the LibTooling framework for running a +Clang tool with the basic Clang diagnostics by syntax checking specific files +in a fast, command line interface. It can also accept flags to re-display the +diagnostics in different formats with different flags, suitable for use driving +an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply +fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for +instructions on how to setup and used `clang-check`. + +``clang-format`` +~~~~~~~~~~~~~~~~ + +Clang-format is both a :doc:`library ` and a :doc:`stand-alone tool +` with the goal of automatically reformatting C++ sources files +according to configurable style guides. To do so, clang-format uses Clang's +``Lexer`` to transform an input file into a token stream and then changes all +the whitespace around those tokens. The goal is for clang-format to both serve +both as a user tool (ideally with powerful IDE integrations) and part of other +refactoring tools, e.g. to do a reformatting of all the lines changed during a +renaming. + +``cpp11-migrate`` +~~~~~~~~~~~~~~~~~ +``cpp11-migrate`` migrates C++ code to use C++11 features where appropriate. +Currently it can: + +* convert loops to range-based for loops; + +* convert null pointer constants (like ``NULL`` or ``0``) to C++11 ``nullptr``. + +Extra Clang Tools +================= + +As various categories of Clang Tools are added to the extra repository, +they'll be tracked here. The focus of this documentation is on the scope +and features of the tools for other tool developers; each tool should +provide its own user-focused documentation. + +Ideas for new Tools +=================== + +* C++ cast conversion tool. Will convert C-style casts (``(type) value``) to + appropriate C++ cast (``static_cast``, ``const_cast`` or + ``reinterpret_cast``). +* Non-member ``begin()`` and ``end()`` conversion tool. Will convert + ``foo.begin()`` into ``begin(foo)`` and similarly for ``end()``, where + ``foo`` is a standard container. We could also detect similar patterns for + arrays. +* ``tr1`` removal tool. Will migrate source code from using TR1 library + features to C++11 library. For example: + + .. code-block:: c++ + + #include + int main() + { + std::tr1::unordered_map ma; + std::cout << ma.size () << std::endl; + return 0; + } + + should be rewritten to: + + .. code-block:: c++ + + #include + int main() + { + std::unordered_map ma; + std::cout << ma.size () << std::endl; + return 0; + } + +* A tool to remove ``auto``. Will convert ``auto`` to an explicit type or add + comments with deduced types. The motivation is that there are developers + that don't want to use ``auto`` because they are afraid that they might lose + control over their code. + diff --git a/docs/DriverInternals.html b/docs/DriverInternals.html deleted file mode 100644 index ce707b990d1f..000000000000 --- a/docs/DriverInternals.html +++ /dev/null @@ -1,523 +0,0 @@ - - - - Clang Driver Manual - - - - - - - - -
- -

Driver Design & Internals

- - - - - -

Introduction

- - -

This document describes the Clang driver. The purpose of this - document is to describe both the motivation and design goals - for the driver, as well as details of the internal - implementation.

- - -

Features and Goals

- - -

The Clang driver is intended to be a production quality - compiler driver providing access to the Clang compiler and - tools, with a command line interface which is compatible with - the gcc driver.

- -

Although the driver is part of and driven by the Clang - project, it is logically a separate tool which shares many of - the same goals as Clang:

- -

Features:

- - - -

GCC Compatibility

- - -

The number one goal of the driver is to ease the adoption of - Clang by allowing users to drop Clang into a build system - which was designed to call GCC. Although this makes the driver - much more complicated than might otherwise be necessary, we - decided that being very compatible with the gcc command line - interface was worth it in order to allow users to quickly test - clang on their projects.

- - -

Flexible

- - -

The driver was designed to be flexible and easily accommodate - new uses as we grow the clang and LLVM infrastructure. As one - example, the driver can easily support the introduction of - tools which have an integrated assembler; something we hope to - add to LLVM in the future.

- -

Similarly, most of the driver functionality is kept in a - library which can be used to build other tools which want to - implement or accept a gcc like interface.

- - -

Low Overhead

- - -

The driver should have as little overhead as possible. In - practice, we found that the gcc driver by itself incurred a - small but meaningful overhead when compiling many small - files. The driver doesn't do much work compared to a - compilation, but we have tried to keep it as efficient as - possible by following a few simple principles:

-
    -
  • Avoid memory allocation and string copying when - possible.
    • - -
  • Don't parse arguments more than once.
    • - -
  • Provide a few simple interfaces for efficiently searching - arguments.
    • -
- - -

Simple

- - -

Finally, the driver was designed to be "as simple as - possible", given the other goals. Notably, trying to be - completely compatible with the gcc driver adds a significant - amount of complexity. However, the design of the driver - attempts to mitigate this complexity by dividing the process - into a number of independent stages instead of a single - monolithic task.

- - -

Internal Design and Implementation

- - - - - -

Internals Introduction

- - -

In order to satisfy the stated goals, the driver was designed - to completely subsume the functionality of the gcc executable; - that is, the driver should not need to delegate to gcc to - perform subtasks. On Darwin, this implies that the Clang - driver also subsumes the gcc driver-driver, which is used to - implement support for building universal images (binaries and - object files). This also implies that the driver should be - able to call the language specific compilers (e.g. cc1) - directly, which means that it must have enough information to - forward command line arguments to child processes - correctly.

- - -

Design Overview

- - -

The diagram below shows the significant components of the - driver architecture and how they relate to one another. The - orange components represent concrete data structures built by - the driver, the green components indicate conceptually - distinct stages which manipulate these data structures, and - the blue components are important helper classes.

- -
- - Driver Architecture Diagram - -
- - -

Driver Stages

- - -

The driver functionality is conceptually divided into five stages:

- -
    -
  1. - Parse: Option Parsing - -

    The command line argument strings are decomposed into - arguments (Arg instances). The driver expects to - understand all available options, although there is some - facility for just passing certain classes of options - through (like -Wl,).

    - -

    Each argument corresponds to exactly one - abstract Option definition, which describes how - the option is parsed along with some additional - metadata. The Arg instances themselves are lightweight and - merely contain enough information for clients to determine - which option they correspond to and their values (if they - have additional parameters).

    - -

    For example, a command line like "-Ifoo -I foo" would - parse to two Arg instances (a JoinedArg and a SeparateArg - instance), but each would refer to the same Option.

    - -

    Options are lazily created in order to avoid populating - all Option classes when the driver is loaded. Most of the - driver code only needs to deal with options by their - unique ID (e.g., options::OPT_I),

    - -

    Arg instances themselves do not generally store the - values of parameters. In many cases, this would - simply result in creating unnecessary string - copies. Instead, Arg instances are always embedded inside - an ArgList structure, which contains the original vector - of argument strings. Each Arg itself only needs to contain - an index into this vector instead of storing its values - directly.

    - -

    The clang driver can dump the results of this - stage using the -ccc-print-options flag (which - must precede any actual command line arguments). For - example:

    - 
    -            $ clang -ccc-print-options -Xarch_i386 -fomit-frame-pointer -Wa,-fast -Ifoo -I foo t.c
-            Option 0 - Name: "-Xarch_", Values: {"i386", "-fomit-frame-pointer"}
-            Option 1 - Name: "-Wa,", Values: {"-fast"}
-            Option 2 - Name: "-I", Values: {"foo"}
-            Option 3 - Name: "-I", Values: {"foo"}
-            Option 4 - Name: "<input>", Values: {"t.c"}
-
    - -

    After this stage is complete the command line should be - broken down into well defined option objects with their - appropriate parameters. Subsequent stages should rarely, - if ever, need to do any string processing.

    -
    2. - -
  2. - Pipeline: Compilation Job Construction - -

    Once the arguments are parsed, the tree of subprocess - jobs needed for the desired compilation sequence are - constructed. This involves determining the input files and - their types, what work is to be done on them (preprocess, - compile, assemble, link, etc.), and constructing a list of - Action instances for each task. The result is a list of - one or more top-level actions, each of which generally - corresponds to a single output (for example, an object or - linked executable).

    - -

    The majority of Actions correspond to actual tasks, - however there are two special Actions. The first is - InputAction, which simply serves to adapt an input - argument for use as an input to other Actions. The second - is BindArchAction, which conceptually alters the - architecture to be used for all of its input Actions.

    - -

    The clang driver can dump the results of this - stage using the -ccc-print-phases flag. For - example:

    - 
    -            $ clang -ccc-print-phases -x c t.c -x assembler t.s
-            0: input, "t.c", c
-            1: preprocessor, {0}, cpp-output
-            2: compiler, {1}, assembler
-            3: assembler, {2}, object
-            4: input, "t.s", assembler
-            5: assembler, {4}, object
-            6: linker, {3, 5}, image
-
    -

    Here the driver is constructing seven distinct actions, - four to compile the "t.c" input into an object file, two to - assemble the "t.s" input, and one to link them together.

    - -

    A rather different compilation pipeline is shown here; in - this example there are two top level actions to compile - the input files into two separate object files, where each - object file is built using lipo to merge results - built for two separate architectures.

    - 
    -            $ clang -ccc-print-phases -c -arch i386 -arch x86_64 t0.c t1.c
-            0: input, "t0.c", c
-            1: preprocessor, {0}, cpp-output
-            2: compiler, {1}, assembler
-            3: assembler, {2}, object
-            4: bind-arch, "i386", {3}, object
-            5: bind-arch, "x86_64", {3}, object
-            6: lipo, {4, 5}, object
-            7: input, "t1.c", c
-            8: preprocessor, {7}, cpp-output
-            9: compiler, {8}, assembler
-            10: assembler, {9}, object
-            11: bind-arch, "i386", {10}, object
-            12: bind-arch, "x86_64", {10}, object
-            13: lipo, {11, 12}, object
-
    - -

    After this stage is complete the compilation process is - divided into a simple set of actions which need to be - performed to produce intermediate or final outputs (in - some cases, like -fsyntax-only, there is no - "real" final output). Phases are well known compilation - steps, such as "preprocess", "compile", "assemble", - "link", etc.

    -
    3. - -
  3. - Bind: Tool & Filename Selection - -

    This stage (in conjunction with the Translate stage) - turns the tree of Actions into a list of actual subprocess - to run. Conceptually, the driver performs a top down - matching to assign Action(s) to Tools. The ToolChain is - responsible for selecting the tool to perform a particular - action; once selected the driver interacts with the tool - to see if it can match additional actions (for example, by - having an integrated preprocessor). - -

    Once Tools have been selected for all actions, the driver - determines how the tools should be connected (for example, - using an inprocess module, pipes, temporary files, or user - provided filenames). If an output file is required, the - driver also computes the appropriate file name (the suffix - and file location depend on the input types and options - such as -save-temps). - -

    The driver interacts with a ToolChain to perform the Tool - bindings. Each ToolChain contains information about all - the tools needed for compilation for a particular - architecture, platform, and operating system. A single - driver invocation may query multiple ToolChains during one - compilation in order to interact with tools for separate - architectures.

    - -

    The results of this stage are not computed directly, but - the driver can print the results via - the -ccc-print-bindings option. For example:

    - 
    -            $ clang -ccc-print-bindings -arch i386 -arch ppc t0.c
-            # "i386-apple-darwin9" - "clang", inputs: ["t0.c"], output: "/tmp/cc-Sn4RKF.s"
-            # "i386-apple-darwin9" - "darwin::Assemble", inputs: ["/tmp/cc-Sn4RKF.s"], output: "/tmp/cc-gvSnbS.o"
-            # "i386-apple-darwin9" - "darwin::Link", inputs: ["/tmp/cc-gvSnbS.o"], output: "/tmp/cc-jgHQxi.out"
-            # "ppc-apple-darwin9" - "gcc::Compile", inputs: ["t0.c"], output: "/tmp/cc-Q0bTox.s"
-            # "ppc-apple-darwin9" - "gcc::Assemble", inputs: ["/tmp/cc-Q0bTox.s"], output: "/tmp/cc-WCdicw.o"
-            # "ppc-apple-darwin9" - "gcc::Link", inputs: ["/tmp/cc-WCdicw.o"], output: "/tmp/cc-HHBEBh.out"
-            # "i386-apple-darwin9" - "darwin::Lipo", inputs: ["/tmp/cc-jgHQxi.out", "/tmp/cc-HHBEBh.out"], output: "a.out"
-
    - -

    This shows the tool chain, tool, inputs and outputs which - have been bound for this compilation sequence. Here clang - is being used to compile t0.c on the i386 architecture and - darwin specific versions of the tools are being used to - assemble and link the result, but generic gcc versions of - the tools are being used on PowerPC.

    -
    4. - -
  4. - Translate: Tool Specific Argument Translation - -

    Once a Tool has been selected to perform a particular - Action, the Tool must construct concrete Jobs which will be - executed during compilation. The main work is in translating - from the gcc style command line options to whatever options - the subprocess expects.

    - -

    Some tools, such as the assembler, only interact with a - handful of arguments and just determine the path of the - executable to call and pass on their input and output - arguments. Others, like the compiler or the linker, may - translate a large number of arguments in addition.

    - -

    The ArgList class provides a number of simple helper - methods to assist with translating arguments; for example, - to pass on only the last of arguments corresponding to some - option, or all arguments for an option.

    - -

    The result of this stage is a list of Jobs (executable - paths and argument strings) to execute.

    -
    5. - -
  5. - Execute -

    Finally, the compilation pipeline is executed. This is - mostly straightforward, although there is some interaction - with options - like -pipe, -pass-exit-codes - and -time.

    -
    6. - -
- - -

Additional Notes

- - -

The Compilation Object

- -

The driver constructs a Compilation object for each set of - command line arguments. The Driver itself is intended to be - invariant during construction of a Compilation; an IDE should be - able to construct a single long lived driver instance to use - for an entire build, for example.

- -

The Compilation object holds information that is particular - to each compilation sequence. For example, the list of used - temporary files (which must be removed once compilation is - finished) and result files (which should be removed if - compilation fails).

- -

Unified Parsing & Pipelining

- -

Parsing and pipelining both occur without reference to a - Compilation instance. This is by design; the driver expects that - both of these phases are platform neutral, with a few very well - defined exceptions such as whether the platform uses a driver - driver.

- -

ToolChain Argument Translation

- -

In order to match gcc very closely, the clang driver - currently allows tool chains to perform their own translation of - the argument list (into a new ArgList data structure). Although - this allows the clang driver to match gcc easily, it also makes - the driver operation much harder to understand (since the Tools - stop seeing some arguments the user provided, and see new ones - instead).

- -

For example, on Darwin -gfull gets translated into two - separate arguments, -g - and -fno-eliminate-unused-debug-symbols. Trying to write Tool - logic to do something with -gfull will not work, because Tool - argument translation is done after the arguments have been - translated.

- -

A long term goal is to remove this tool chain specific - translation, and instead force each tool to change its own logic - to do the right thing on the untranslated original arguments.

- -

Unused Argument Warnings

-

The driver operates by parsing all arguments but giving Tools - the opportunity to choose which arguments to pass on. One - downside of this infrastructure is that if the user misspells - some option, or is confused about which options to use, some - command line arguments the user really cared about may go - unused. This problem is particularly important when using - clang as a compiler, since the clang compiler does not support - anywhere near all the options that gcc does, and we want to make - sure users know which ones are being used.

- -

To support this, the driver maintains a bit associated with - each argument of whether it has been used (at all) during the - compilation. This bit usually doesn't need to be set by hand, - as the key ArgList accessors will set it automatically.

- -

When a compilation is successful (there are no errors), the - driver checks the bit and emits an "unused argument" warning for - any arguments which were never accessed. This is conservative - (the argument may not have been used to do what the user wanted) - but still catches the most obvious cases.

- - -

Relation to GCC Driver Concepts

- - -

For those familiar with the gcc driver, this section provides - a brief overview of how things from the gcc driver map to the - clang driver.

- -
    -
  • - Driver Driver -

    The driver driver is fully integrated into the clang - driver. The driver simply constructs additional Actions to - bind the architecture during the Pipeline - phase. The tool chain specific argument translation is - responsible for handling -Xarch_.

    - -

    The one caveat is that this approach - requires -Xarch_ not be used to alter the - compilation itself (for example, one cannot - provide -S as an -Xarch_ argument). The - driver attempts to reject such invocations, and overall - there isn't a good reason to abuse -Xarch_ to - that end in practice.

    - -

    The upside is that the clang driver is more efficient and - does little extra work to support universal builds. It also - provides better error reporting and UI consistency.

    -
    • - -
  • - Specs -

    The clang driver has no direct correspondent for - "specs". The majority of the functionality that is - embedded in specs is in the Tool specific argument - translation routines. The parts of specs which control the - compilation pipeline are generally part of - the Pipeline stage.

    -
    • - -
  • - Toolchains -

    The gcc driver has no direct understanding of tool - chains. Each gcc binary roughly corresponds to the - information which is embedded inside a single - ToolChain.

    - -

    The clang driver is intended to be portable and support - complex compilation environments. All platform and tool - chain specific code should be protected behind either - abstract or well defined interfaces (such as whether the - platform supports use as a driver driver).

    -
    • -
-
- - diff --git a/docs/DriverInternals.rst b/docs/DriverInternals.rst new file mode 100644 index 000000000000..c779555dae37 --- /dev/null +++ b/docs/DriverInternals.rst @@ -0,0 +1,400 @@ +========================= +Driver Design & Internals +========================= + +.. contents:: + :local: + +Introduction +============ + +This document describes the Clang driver. The purpose of this document +is to describe both the motivation and design goals for the driver, as +well as details of the internal implementation. + +Features and Goals +================== + +The Clang driver is intended to be a production quality compiler driver +providing access to the Clang compiler and tools, with a command line +interface which is compatible with the gcc driver. + +Although the driver is part of and driven by the Clang project, it is +logically a separate tool which shares many of the same goals as Clang: + +.. contents:: Features + :local: + +GCC Compatibility +----------------- + +The number one goal of the driver is to ease the adoption of Clang by +allowing users to drop Clang into a build system which was designed to +call GCC. Although this makes the driver much more complicated than +might otherwise be necessary, we decided that being very compatible with +the gcc command line interface was worth it in order to allow users to +quickly test clang on their projects. + +Flexible +-------- + +The driver was designed to be flexible and easily accommodate new uses +as we grow the clang and LLVM infrastructure. As one example, the driver +can easily support the introduction of tools which have an integrated +assembler; something we hope to add to LLVM in the future. + +Similarly, most of the driver functionality is kept in a library which +can be used to build other tools which want to implement or accept a gcc +like interface. + +Low Overhead +------------ + +The driver should have as little overhead as possible. In practice, we +found that the gcc driver by itself incurred a small but meaningful +overhead when compiling many small files. The driver doesn't do much +work compared to a compilation, but we have tried to keep it as +efficient as possible by following a few simple principles: + +- Avoid memory allocation and string copying when possible. +- Don't parse arguments more than once. +- Provide a few simple interfaces for efficiently searching arguments. + +Simple +------ + +Finally, the driver was designed to be "as simple as possible", given +the other goals. Notably, trying to be completely compatible with the +gcc driver adds a significant amount of complexity. However, the design +of the driver attempts to mitigate this complexity by dividing the +process into a number of independent stages instead of a single +monolithic task. + +Internal Design and Implementation +================================== + +.. contents:: + :local: + :depth: 1 + +Internals Introduction +---------------------- + +In order to satisfy the stated goals, the driver was designed to +completely subsume the functionality of the gcc executable; that is, the +driver should not need to delegate to gcc to perform subtasks. On +Darwin, this implies that the Clang driver also subsumes the gcc +driver-driver, which is used to implement support for building universal +images (binaries and object files). This also implies that the driver +should be able to call the language specific compilers (e.g. cc1) +directly, which means that it must have enough information to forward +command line arguments to child processes correctly. + +Design Overview +--------------- + +The diagram below shows the significant components of the driver +architecture and how they relate to one another. The orange components +represent concrete data structures built by the driver, the green +components indicate conceptually distinct stages which manipulate these +data structures, and the blue components are important helper classes. + +.. image:: DriverArchitecture.png + :align: center + :alt: Driver Architecture Diagram + +Driver Stages +------------- + +The driver functionality is conceptually divided into five stages: + +#. **Parse: Option Parsing** + + The command line argument strings are decomposed into arguments + (``Arg`` instances). The driver expects to understand all available + options, although there is some facility for just passing certain + classes of options through (like ``-Wl,``). + + Each argument corresponds to exactly one abstract ``Option`` + definition, which describes how the option is parsed along with some + additional metadata. The Arg instances themselves are lightweight and + merely contain enough information for clients to determine which + option they correspond to and their values (if they have additional + parameters). + + For example, a command line like "-Ifoo -I foo" would parse to two + Arg instances (a JoinedArg and a SeparateArg instance), but each + would refer to the same Option. + + Options are lazily created in order to avoid populating all Option + classes when the driver is loaded. Most of the driver code only needs + to deal with options by their unique ID (e.g., ``options::OPT_I``), + + Arg instances themselves do not generally store the values of + parameters. In many cases, this would simply result in creating + unnecessary string copies. Instead, Arg instances are always embedded + inside an ArgList structure, which contains the original vector of + argument strings. Each Arg itself only needs to contain an index into + this vector instead of storing its values directly. + + The clang driver can dump the results of this stage using the + ``-ccc-print-options`` flag (which must precede any actual command + line arguments). For example: + + .. code-block:: console + + $ clang -ccc-print-options -Xarch_i386 -fomit-frame-pointer -Wa,-fast -Ifoo -I foo t.c + Option 0 - Name: "-Xarch_", Values: {"i386", "-fomit-frame-pointer"} + Option 1 - Name: "-Wa,", Values: {"-fast"} + Option 2 - Name: "-I", Values: {"foo"} + Option 3 - Name: "-I", Values: {"foo"} + Option 4 - Name: "", Values: {"t.c"} + + After this stage is complete the command line should be broken down + into well defined option objects with their appropriate parameters. + Subsequent stages should rarely, if ever, need to do any string + processing. + +#. **Pipeline: Compilation Job Construction** + + Once the arguments are parsed, the tree of subprocess jobs needed for + the desired compilation sequence are constructed. This involves + determining the input files and their types, what work is to be done + on them (preprocess, compile, assemble, link, etc.), and constructing + a list of Action instances for each task. The result is a list of one + or more top-level actions, each of which generally corresponds to a + single output (for example, an object or linked executable). + + The majority of Actions correspond to actual tasks, however there are + two special Actions. The first is InputAction, which simply serves to + adapt an input argument for use as an input to other Actions. The + second is BindArchAction, which conceptually alters the architecture + to be used for all of its input Actions. + + The clang driver can dump the results of this stage using the + ``-ccc-print-phases`` flag. For example: + + .. code-block:: console + + $ clang -ccc-print-phases -x c t.c -x assembler t.s + 0: input, "t.c", c + 1: preprocessor, {0}, cpp-output + 2: compiler, {1}, assembler + 3: assembler, {2}, object + 4: input, "t.s", assembler + 5: assembler, {4}, object + 6: linker, {3, 5}, image + + Here the driver is constructing seven distinct actions, four to + compile the "t.c" input into an object file, two to assemble the + "t.s" input, and one to link them together. + + A rather different compilation pipeline is shown here; in this + example there are two top level actions to compile the input files + into two separate object files, where each object file is built using + ``lipo`` to merge results built for two separate architectures. + + .. code-block:: console + + $ clang -ccc-print-phases -c -arch i386 -arch x86_64 t0.c t1.c + 0: input, "t0.c", c + 1: preprocessor, {0}, cpp-output + 2: compiler, {1}, assembler + 3: assembler, {2}, object + 4: bind-arch, "i386", {3}, object + 5: bind-arch, "x86_64", {3}, object + 6: lipo, {4, 5}, object + 7: input, "t1.c", c + 8: preprocessor, {7}, cpp-output + 9: compiler, {8}, assembler + 10: assembler, {9}, object + 11: bind-arch, "i386", {10}, object + 12: bind-arch, "x86_64", {10}, object + 13: lipo, {11, 12}, object + + After this stage is complete the compilation process is divided into + a simple set of actions which need to be performed to produce + intermediate or final outputs (in some cases, like ``-fsyntax-only``, + there is no "real" final output). Phases are well known compilation + steps, such as "preprocess", "compile", "assemble", "link", etc. + +#. **Bind: Tool & Filename Selection** + + This stage (in conjunction with the Translate stage) turns the tree + of Actions into a list of actual subprocess to run. Conceptually, the + driver performs a top down matching to assign Action(s) to Tools. The + ToolChain is responsible for selecting the tool to perform a + particular action; once selected the driver interacts with the tool + to see if it can match additional actions (for example, by having an + integrated preprocessor). + + Once Tools have been selected for all actions, the driver determines + how the tools should be connected (for example, using an inprocess + module, pipes, temporary files, or user provided filenames). If an + output file is required, the driver also computes the appropriate + file name (the suffix and file location depend on the input types and + options such as ``-save-temps``). + + The driver interacts with a ToolChain to perform the Tool bindings. + Each ToolChain contains information about all the tools needed for + compilation for a particular architecture, platform, and operating + system. A single driver invocation may query multiple ToolChains + during one compilation in order to interact with tools for separate + architectures. + + The results of this stage are not computed directly, but the driver + can print the results via the ``-ccc-print-bindings`` option. For + example: + + .. code-block:: console + + $ clang -ccc-print-bindings -arch i386 -arch ppc t0.c + # "i386-apple-darwin9" - "clang", inputs: ["t0.c"], output: "/tmp/cc-Sn4RKF.s" + # "i386-apple-darwin9" - "darwin::Assemble", inputs: ["/tmp/cc-Sn4RKF.s"], output: "/tmp/cc-gvSnbS.o" + # "i386-apple-darwin9" - "darwin::Link", inputs: ["/tmp/cc-gvSnbS.o"], output: "/tmp/cc-jgHQxi.out" + # "ppc-apple-darwin9" - "gcc::Compile", inputs: ["t0.c"], output: "/tmp/cc-Q0bTox.s" + # "ppc-apple-darwin9" - "gcc::Assemble", inputs: ["/tmp/cc-Q0bTox.s"], output: "/tmp/cc-WCdicw.o" + # "ppc-apple-darwin9" - "gcc::Link", inputs: ["/tmp/cc-WCdicw.o"], output: "/tmp/cc-HHBEBh.out" + # "i386-apple-darwin9" - "darwin::Lipo", inputs: ["/tmp/cc-jgHQxi.out", "/tmp/cc-HHBEBh.out"], output: "a.out" + + This shows the tool chain, tool, inputs and outputs which have been + bound for this compilation sequence. Here clang is being used to + compile t0.c on the i386 architecture and darwin specific versions of + the tools are being used to assemble and link the result, but generic + gcc versions of the tools are being used on PowerPC. + +#. **Translate: Tool Specific Argument Translation** + + Once a Tool has been selected to perform a particular Action, the + Tool must construct concrete Jobs which will be executed during + compilation. The main work is in translating from the gcc style + command line options to whatever options the subprocess expects. + + Some tools, such as the assembler, only interact with a handful of + arguments and just determine the path of the executable to call and + pass on their input and output arguments. Others, like the compiler + or the linker, may translate a large number of arguments in addition. + + The ArgList class provides a number of simple helper methods to + assist with translating arguments; for example, to pass on only the + last of arguments corresponding to some option, or all arguments for + an option. + + The result of this stage is a list of Jobs (executable paths and + argument strings) to execute. + +#. **Execute** + + Finally, the compilation pipeline is executed. This is mostly + straightforward, although there is some interaction with options like + ``-pipe``, ``-pass-exit-codes`` and ``-time``. + +Additional Notes +---------------- + +The Compilation Object +^^^^^^^^^^^^^^^^^^^^^^ + +The driver constructs a Compilation object for each set of command line +arguments. The Driver itself is intended to be invariant during +construction of a Compilation; an IDE should be able to construct a +single long lived driver instance to use for an entire build, for +example. + +The Compilation object holds information that is particular to each +compilation sequence. For example, the list of used temporary files +(which must be removed once compilation is finished) and result files +(which should be removed if compilation fails). + +Unified Parsing & Pipelining +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Parsing and pipelining both occur without reference to a Compilation +instance. This is by design; the driver expects that both of these +phases are platform neutral, with a few very well defined exceptions +such as whether the platform uses a driver driver. + +ToolChain Argument Translation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to match gcc very closely, the clang driver currently allows +tool chains to perform their own translation of the argument list (into +a new ArgList data structure). Although this allows the clang driver to +match gcc easily, it also makes the driver operation much harder to +understand (since the Tools stop seeing some arguments the user +provided, and see new ones instead). + +For example, on Darwin ``-gfull`` gets translated into two separate +arguments, ``-g`` and ``-fno-eliminate-unused-debug-symbols``. Trying to +write Tool logic to do something with ``-gfull`` will not work, because +Tool argument translation is done after the arguments have been +translated. + +A long term goal is to remove this tool chain specific translation, and +instead force each tool to change its own logic to do the right thing on +the untranslated original arguments. + +Unused Argument Warnings +^^^^^^^^^^^^^^^^^^^^^^^^ + +The driver operates by parsing all arguments but giving Tools the +opportunity to choose which arguments to pass on. One downside of this +infrastructure is that if the user misspells some option, or is confused +about which options to use, some command line arguments the user really +cared about may go unused. This problem is particularly important when +using clang as a compiler, since the clang compiler does not support +anywhere near all the options that gcc does, and we want to make sure +users know which ones are being used. + +To support this, the driver maintains a bit associated with each +argument of whether it has been used (at all) during the compilation. +This bit usually doesn't need to be set by hand, as the key ArgList +accessors will set it automatically. + +When a compilation is successful (there are no errors), the driver +checks the bit and emits an "unused argument" warning for any arguments +which were never accessed. This is conservative (the argument may not +have been used to do what the user wanted) but still catches the most +obvious cases. + +Relation to GCC Driver Concepts +------------------------------- + +For those familiar with the gcc driver, this section provides a brief +overview of how things from the gcc driver map to the clang driver. + +- **Driver Driver** + + The driver driver is fully integrated into the clang driver. The + driver simply constructs additional Actions to bind the architecture + during the *Pipeline* phase. The tool chain specific argument + translation is responsible for handling ``-Xarch_``. + + The one caveat is that this approach requires ``-Xarch_`` not be used + to alter the compilation itself (for example, one cannot provide + ``-S`` as an ``-Xarch_`` argument). The driver attempts to reject + such invocations, and overall there isn't a good reason to abuse + ``-Xarch_`` to that end in practice. + + The upside is that the clang driver is more efficient and does little + extra work to support universal builds. It also provides better error + reporting and UI consistency. + +- **Specs** + + The clang driver has no direct correspondent for "specs". The + majority of the functionality that is embedded in specs is in the + Tool specific argument translation routines. The parts of specs which + control the compilation pipeline are generally part of the *Pipeline* + stage. + +- **Toolchains** + + The gcc driver has no direct understanding of tool chains. Each gcc + binary roughly corresponds to the information which is embedded + inside a single ToolChain. + + The clang driver is intended to be portable and support complex + compilation environments. All platform and tool chain specific code + should be protected behind either abstract or well defined interfaces + (such as whether the platform supports use as a driver driver). diff --git a/docs/ExternalClangExamples.rst b/docs/ExternalClangExamples.rst new file mode 100644 index 000000000000..c7fd4c51faac --- /dev/null +++ b/docs/ExternalClangExamples.rst @@ -0,0 +1,80 @@ +======================= +External Clang Examples +======================= + +Introduction +============ + +This page provides some examples of the kinds of things that people have +done with Clang that might serve as useful guides (or starting points) from +which to develop your own tools. They may be helpful even for something as +banal (but necessary) as how to set up your build to integrate Clang. + +Clang's library-based design is deliberately aimed at facilitating use by +external projects, and we are always interested in improving Clang to +better serve our external users. Some typical categories of applications +where Clang is used are: + +- Static analysis. +- Documentation/cross-reference generation. + +If you know of (or wrote!) a tool or project using Clang, please send an +email to Clang's `development discussion mailing list +`_ to have it added. +(or if you are already a Clang contributor, feel free to directly commit +additions). Since the primary purpose of this page is to provide examples +that can help developers, generally they must have code available. + +List of projects and tools +========================== + +``_ + "RTags is a client/server application that indexes c/c++ code and keeps + a persistent in-memory database of references, symbolnames, completions + etc." + +``_ + "A C/C++ source code indexer and navigator" + +``_ + "qconnectlint is a Clang tool for statically verifying the consistency + of signal and slot connections made with Qt's ``QObject::connect``." + +``_ + "The Woboq Code Browser is a web-based code browser for C/C++ projects. + Check out ``_ for an example!" + +``_ + "DXR is a source code cross-reference tool that uses static analysis + data collected by instrumented compilers." + +``_ + "This tool performs a number of operations on C-language source files." + +``_ + "A coding rule validation add-on for LLVM/clang. Crisp rules are written + in Prolog. A high-level declarative DSL to easily write new rules is under + development. It will be called CRISP, an acronym for *Coding Rules in + Sugared Prolog*." + +``_ + "Generate tag file for C++ source code." + +``_ + "This is an indexer for C and C++ based on the libclang library." + +``_ + "Linty - C/C++ Style Checking with Python & libclang." + +``_ + "cmonster is a Python wrapper for the Clang C++ parser." + +``_ + "Constantine is a toy project to learn how to write clang plugin. + Implements pseudo const analysis. Generates warnings about variables, + which were declared without const qualifier." + +``_ + "cldoc is a Clang based documentation generator for C and C++. + cldoc tries to solve the issue of writing C/C++ software documentation + with a modern, non-intrusive and robust approach." diff --git a/docs/FAQ.rst b/docs/FAQ.rst new file mode 100644 index 000000000000..4c4f8a87e3bc --- /dev/null +++ b/docs/FAQ.rst @@ -0,0 +1,64 @@ +================================ +Frequently Asked Questions (FAQ) +================================ + +.. contents:: + :local: + +Driver +====== + +I run ``clang -cc1 ...`` and get weird errors about missing headers +------------------------------------------------------------------- + +Given this source file: + +.. code-block:: c + + #include + + int main() { + printf("Hello world\n"); + } + + +If you run: + +.. code-block:: console + + $ clang -cc1 hello.c + hello.c:1:10: fatal error: 'stdio.h' file not found + #include + ^ + 1 error generated. + +``clang -cc1`` is the frontend, ``clang`` is the :doc:`driver +`. The driver invokes the frontend with options appropriate +for your system. To see these options, run: + +.. code-block:: console + + $ clang -### -c hello.c + +Some clang command line options are driver-only options, some are frontend-only +options. Frontend-only options are intended to be used only by clang developers. +Users should not run ``clang -cc1`` directly, because ``-cc1`` options are not +guaranteed to be stable. + +If you want to use a frontend-only option ("a ``-cc1`` option"), for example +``-ast-dump``, then you need to take the ``clang -cc1`` line generated by the +driver and add the option you need. Alternatively, you can run +``clang -Xclang