book

Programming Rust, 2nd Edition

by Jim Blandy, Jason Orendorff, Leonora F. S. Tindall

June 2021

Intermediate to advanced

738 pages

18h 47m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Includes

Has Sandbox

Who Should Read This BookWhy We Wrote This BookNavigating This BookConventions Used in This BookUsing Code ExamplesO’Reilly Online LearningHow to Contact UsAcknowledgments
Rust Shoulders the Load for YouParallel Programming Is TamedAnd Yet Rust Is Still FastRust Makes Collaboration Easier
rustup and CargoRust FunctionsWriting and Running Unit TestsHandling Command-Line ArgumentsServing Pages to the WebConcurrencyWhat the Mandelbrot Set Actually IsParsing Pair Command-Line ArgumentsMapping from Pixels to Complex NumbersPlotting the SetWriting Image FilesA Concurrent Mandelbrot ProgramRunning the Mandelbrot PlotterSafety Is InvisibleFilesystems and Command-Line ToolsThe Command-Line InterfaceReading and Writing FilesFind and Replace
Fixed-Width Numeric TypesInteger TypesChecked, Wrapping, Saturating, and Overflowing ArithmeticFloating-Point TypesThe bool TypeCharactersTuplesPointer TypesReferencesBoxesRaw PointersArrays, Vectors, and SlicesArraysVectorsSlicesString TypesString LiteralsByte StringsStrings in MemoryStringUsing StringsOther String-Like TypesType AliasesBeyond the Basics
OwnershipMovesMore Operations That MoveMoves and Control FlowMoves and Indexed ContentCopy Types: The Exception to MovesRc and Arc: Shared Ownership
References to ValuesWorking with ReferencesRust References Versus C++ ReferencesAssigning ReferencesReferences to ReferencesComparing ReferencesReferences Are Never NullBorrowing References to Arbitrary ExpressionsReferences to Slices and Trait ObjectsReference SafetyBorrowing a Local VariableReceiving References as Function ArgumentsPassing References to FunctionsReturning ReferencesStructs Containing ReferencesDistinct Lifetime ParametersOmitting Lifetime ParametersSharing Versus MutationTaking Arms Against a Sea of Objects
An Expression LanguagePrecedence and AssociativityBlocks and SemicolonsDeclarationsif and matchif letLoopsControl Flow in Loopsreturn ExpressionsWhy Rust Has loopFunction and Method CallsFields and ElementsReference OperatorsArithmetic, Bitwise, Comparison, and Logical OperatorsAssignmentType CastsClosuresOnward
PanicUnwindingAbortingResultCatching ErrorsResult Type AliasesPrinting ErrorsPropagating ErrorsWorking with Multiple Error TypesDealing with Errors That “Can’t Happen”Ignoring ErrorsHandling Errors in main()Declaring a Custom Error TypeWhy Results?
CratesEditionsBuild ProfilesModulesNested ModulesModules in Separate FilesPaths and ImportsThe Standard PreludeMaking use Declarations pubMaking Struct Fields pubStatics and ConstantsTurning a Program into a LibraryThe src/bin DirectoryAttributesTests and DocumentationIntegration TestsDocumentationDoc-TestsSpecifying DependenciesVersionsCargo.lockPublishing Crates to crates.ioWorkspacesMore Nice Things
Named-Field StructsTuple-Like StructsUnit-Like StructsStruct LayoutDefining Methods with implPassing Self as a Box, Rc, or ArcType-Associated FunctionsAssociated ConstsGeneric StructsGeneric Structs with Lifetime ParametersGeneric Structs with Constant ParametersDeriving Common Traits for Struct TypesInterior Mutability

EnumsEnums with DataEnums in MemoryRich Data Structures Using EnumsGeneric EnumsPatternsLiterals, Variables, and Wildcards in PatternsTuple and Struct PatternsArray and Slice PatternsReference PatternsMatch GuardsMatching Multiple PossibilitiesBinding with @ PatternsWhere Patterns Are AllowedPopulating a Binary TreeThe Big Picture
Using TraitsTrait ObjectsGeneric Functions and Type ParametersWhich to UseDefining and Implementing TraitsDefault MethodsTraits and Other People’s TypesSelf in TraitsSubtraitsType-Associated FunctionsFully Qualified Method CallsTraits That Define Relationships Between TypesAssociated Types (or How Iterators Work)Generic Traits (or How Operator Overloading Works)impl TraitAssociated ConstsReverse-Engineering BoundsTraits as a Foundation
Arithmetic and Bitwise OperatorsUnary OperatorsBinary OperatorsCompound Assignment OperatorsEquivalence ComparisonsOrdered ComparisonsIndex and IndexMutOther Operators
DropSizedCloneCopyDeref and DerefMutDefaultAsRef and AsMutBorrow and BorrowMutFrom and IntoTryFrom and TryIntoToOwnedBorrow and ToOwned at Work: The Humble Cow
Capturing VariablesClosures That BorrowClosures That StealFunction and Closure TypesClosure PerformanceClosures and SafetyClosures That KillFnOnceFnMutCopy and Clone for ClosuresCallbacksUsing Closures Effectively
The Iterator and IntoIterator TraitsCreating Iteratorsiter and iter_mut MethodsIntoIterator Implementationsfrom_fn and successorsdrain MethodsOther Iterator SourcesIterator Adaptersmap and filterfilter_map and flat_mapflattentake and take_whileskip and skip_whilepeekablefuseReversible Iterators and revinspectchainenumeratezipby_refcloned, copiedcycleConsuming IteratorsSimple Accumulation: count, sum, productmax, minmax_by, min_bymax_by_key, min_by_keyComparing Item Sequencesany and allposition, rposition, and ExactSizeIteratorfold and rfoldtry_fold and try_rfoldnth, nth_backlastfind, rfind, and find_mapBuilding Collections: collect and FromIteratorThe Extend Traitpartitionfor_each and try_for_eachImplementing Your Own Iterators
OverviewVec<T>Accessing ElementsIterationGrowing and Shrinking VectorsJoiningSplittingSwappingFillingSorting and SearchingComparing SlicesRandom ElementsRust Rules Out Invalidation ErrorsVecDeque<T>BinaryHeap<T>HashMap<K, V> and BTreeMap<K, V>EntriesMap IterationHashSet<T> and BTreeSet<T>Set IterationWhen Equal Values Are DifferentWhole-Set OperationsHashingUsing a Custom Hashing AlgorithmBeyond the Standard Collections
Some Unicode BackgroundASCII, Latin-1, and UnicodeUTF-8Text DirectionalityCharacters (char)Classifying CharactersHandling DigitsCase Conversion for CharactersConversions to and from IntegersString and strCreating String ValuesSimple InspectionAppending and Inserting TextRemoving and Replacing TextConventions for Searching and IteratingPatterns for Searching TextSearching and ReplacingIterating over TextTrimmingCase Conversion for StringsParsing Other Types from StringsConverting Other Types to StringsBorrowing as Other Text-Like TypesAccessing Text as UTF-8Producing Text from UTF-8 DataPutting Off AllocationStrings as Generic CollectionsFormatting ValuesFormatting Text ValuesFormatting NumbersFormatting Other TypesFormatting Values for DebuggingFormatting Pointers for DebuggingReferring to Arguments by Index or NameDynamic Widths and PrecisionsFormatting Your Own TypesUsing the Formatting Language in Your Own CodeRegular ExpressionsBasic Regex UseBuilding Regex Values LazilyNormalizationNormalization FormsThe unicode-normalization Crate
Readers and WritersReadersBuffered ReadersReading LinesCollecting LinesWritersFilesSeekingOther Reader and Writer TypesBinary Data, Compression, and SerializationFiles and DirectoriesOsStr and PathPath and PathBuf MethodsFilesystem Access FunctionsReading DirectoriesPlatform-Specific FeaturesNetworking
Fork-Join Parallelismspawn and joinError Handling Across ThreadsSharing Immutable Data Across ThreadsRayonRevisiting the Mandelbrot SetChannelsSending ValuesReceiving ValuesRunning the PipelineChannel Features and PerformanceThread Safety: Send and SyncPiping Almost Any Iterator to a ChannelBeyond PipelinesShared Mutable StateWhat Is a Mutex?Mutex<T>mut and MutexWhy Mutexes Are Not Always a Good IdeaDeadlockPoisoned MutexesMulticonsumer Channels Using MutexesRead/Write Locks (RwLock<T>)Condition Variables (Condvar)AtomicsGlobal VariablesWhat Hacking Concurrent Code in Rust Is Like
From Synchronous to AsynchronousFuturesAsync Functions and Await ExpressionsCalling Async Functions from Synchronous Code: block_onSpawning Async TasksAsync BlocksBuilding Async Functions from Async BlocksSpawning Async Tasks on a Thread PoolBut Does Your Future Implement Send?Long Running Computations: yield_now and spawn_blockingComparing Asynchronous DesignsA Real Asynchronous HTTP ClientAn Asynchronous Client and ServerError and Result TypesThe ProtocolTaking User Input: Asynchronous StreamsSending PacketsReceiving Packets: More Asynchronous StreamsThe Client’s Main FunctionThe Server’s Main FunctionHandling Chat Connections: Async MutexesThe Group Table: Synchronous MutexesChat Groups: tokio’s Broadcast ChannelsPrimitive Futures and Executors: When Is a Future Worth Polling Again?Invoking Wakers: spawn_blockingImplementing block_onPinningThe Two Life Stages of a FuturePinned PointersThe Unpin TraitWhen Is Asynchronous Code Helpful?
Macro BasicsBasics of Macro ExpansionUnintended ConsequencesRepetitionBuilt-In MacrosDebugging MacrosBuilding the json! MacroFragment TypesRecursion in MacrosUsing Traits with MacrosScoping and HygieneImporting and Exporting MacrosAvoiding Syntax Errors During MatchingBeyond macro_rules!
Unsafe from What?Unsafe BlocksExample: An Efficient ASCII String TypeUnsafe FunctionsUnsafe Block or Unsafe Function?Undefined BehaviorUnsafe TraitsRaw PointersDereferencing Raw Pointers SafelyExample: RefWithFlagNullable PointersType Sizes and AlignmentsPointer ArithmeticMoving into and out of MemoryExample: GapBufferPanic Safety in Unsafe CodeReinterpreting Memory with UnionsMatching UnionsBorrowing Unions
Finding Common Data RepresentationsDeclaring Foreign Functions and VariablesUsing Functions from LibrariesA Raw Interface to libgit2A Safe Interface to libgit2Conclusion

Content preview from Programming Rust, 2nd Edition

Chapter 23. Foreign Functions

Cyberspace. Unthinkable complexity. Lines of light ranged in the non-space of the mind, clusters and constellations of data. Like city lights, receding . . .

William Gibson, Neuromancer

Tragically, not every program in the world is written in Rust. There are many critical libraries and interfaces implemented in other languages that we would like to be able to use in our Rust programs. Rust’s foreign function interface (FFI) lets Rust code call functions written in C, and in some cases C++. Since most operating systems offer C interfaces, Rust’s foreign function interface allows immediate access to all sorts of low-level facilities.

In this chapter, we’ll write a program that links with libgit2, a C library for working with the Git version control system. First, we’ll show what it’s like to use C functions directly from Rust, using the unsafe features demonstrated in the previous chapter. Then, we’ll show how to construct a safe interface to libgit2, taking inspiration from the open source git2-rs crate, which does exactly that.

We’ll assume that you’re familiar with C and the mechanics of compiling and linking C programs. Working with C++ is similar. We’ll also assume that you’re somewhat familiar with the Git version control system.

There do exist Rust crates for communicating with many other languages, including Python, JavaScript, Lua, and Java. We don’t have room to cover them here, but ultimately, all these interfaces are built using the C ...