Hacker News new | past | comments | ask | show | jobs | submit login
The Advanced Rust Programming Language Book Draft (rust-lang.org)
215 points by adamnemecek on July 31, 2015 | hide | past | web | favorite | 47 comments

Author here. Didn't really want to post this to the wider programming community yet, but oh well.

This is basically the first draft. Lots of errors and TODOs.

Source is here if you want to file issues or patches: https://github.com/rust-lang/rust/tree/master/src/doc/tarpl

Changed the title to "The Advanced Rust Programming Language Book Draft". Better :-)?


If you'd prefer that we demote the post until the material is more ready, I think it's reasonable to offer an author that prerogative.

Eh, I'm already at the top of HN. :P

More eyes to find errors before it makes into the beta channel, hopefully!

No problem! Is there someplace we can go to be alerted when it is ready?

So it's in nightly today, so barring a tragedy it will land in stable in ~8 weeks I think. I'll probably repost it everywhere when that happens.

This and The Book are living documents anyway -- they'll never be done. This just literally landed last night, though.

In a book that opens with "Unlike The Rust Programming Language we will be assuming considerable prior knowledge", you don't need the simple ownership example.

Even if assuming considerable knowledge, it's nice to be able to refresh the reader on basics here and there. That text is largely just reserving the right to not explain everything (also I'm moving away from it in general).

Also: what example? There's like a hundred examples.

Edit: If you mean the examples here: https://doc.rust-lang.org/nightly/adv-book/ownership.html

They're a recurring example that we deconstruct in later sections. There's no need to make them needlessly complicated.

Agreed. I work in Go, JS, Python, bash, Lua, Objective-C, Java, and C# (among others) every week. Sometimes I need a quick refresher on the topic at hand.

(How many times I've put a colon at the end of a Lua function line...)

Great to have a resource like this. By way of providing some hopefully constructive feedback, the language seems a bit excessively informal: "Safe Rust is For Reals Totally Safe. Unsafe Rust, unsurprisingly, is not For Reals Totally Safe. In fact, Unsafe Rust lets you do some really crazy unsafe things". I get the idea that's it's trying to be friendly and street, but it's a bit out of place in a document like this (I was just waiting for 'shizzle' to pop up). There also looks to be an excessive use of emphasis (italics).

Haha, yeah I like to be a bit silly here or there. I might tone it down, but on the other hand I find it makes the text a bit less dry to not take yourself too seriously. :)

re italics: https://github.com/rust-lang/rust/pull/27414

I see what you are aiming at, but honestly this informal style is hugely irritating to read for me, and is probably the main reason I haven't delved further into rust - I just can't spend more than 5 minutes reading the guide. It seems like it takes twice as long to get the information across because there are constant "quirky" remarks, weird and anthropomorphisations of computers or code, or "humorous" observations about coders. I agree the italics are annoying; there really isn't any need to stress particular words, people can read and if you write well it will be pretty obvious which words are supposed to be emphasised ("really" really doesn't). In general the tone comes across as a mix between cocky and patronising ("this book contains invaluable information" - how modest).

For example, the two opening paragraphs basically told me nothing that the title didn't. And then we have things like this:

>With that said, Rust is totally a safe programming language.

What the hell kind of a statement is this to put in an advanced programming book? It adds nothing, sounds childish. Just let the content speak for itself, stop trying to be relatable or funny.

Sorry if I'm coming across as bitter and whiny, but I am disappointed that this is suffering from the same problem as the guide for me. I honestly think it would be good for the project to have someone else to be writing these guides.


> Safe Rust is For Reals Totally Safe.

> That's totally awesome.

> Low-level programming cares a lot about data layout. It's a big deal.



For some constructive criticism, I think Julia's docs really hit the right mark. Here is their introduction: http://julia.readthedocs.org/en/release-0.3/manual/introduct... There is a lot of information on that page, a clear mission statement, not too dry but still manages to speak to you like an adult.

I guess there are at least two schools of thought for programming books. There's the one you mention, and there's a different approach that you'll see here and in other books like Learn You a Haskell for Great Good, Brave Clojure, and perhaps most famously, why's (poignant) Guide to Ruby.

I think that there's a place for both of these styles in the world. And perhaps this style can appeal to a person who struggles with the stereotype of computer programming as a serious, dry affair, bereft of human expression, the job of coder cogs in programming factories. Perhaps you could say that the serious style appeals to more people, but maybe that is actually a criticism of the population of programmers, and not of the work?

In regards to sounding childish, I find that in general to be an unusual criticism. Perhaps there are people who speak this way as adults simply because that is who they are? I guess C.S. Lewis sums up my feelings about "being childish":

Critics who treat 'adult' as a term of approval, instead of as a merely descriptive term, cannot be adult themselves. To be concerned about being grown up, to admire the grown up because it is grown up, to blush at the suspicion of being childish; these things are the marks of childhood and adolescence. And in childhood and adolescence they are, in moderation, healthy symptoms. Young things ought to want to grow. But to carry on into middle life or even into early manhood this concern about being adult is a mark of really arrested development. When I was ten, I read fairy tales in secret and would have been ashamed if I had been found doing so. Now that I am fifty I read them openly. When I became a man I put away childish things, including the fear of childishness and the desire to be very grown up.

I agree that there is a place for both styles in the world. Unfortunately when it comes to rust most of the tutorial seem to be in this style, and I thought at least the "advanced" guide would be more "sensible". I enjoyed Learn You a Haskell, but that was an introductory text. If I am reading an "advanced" text on a systems programming language I probably expect it to be a little more formal.

>In regards to sounding childish, I find that in general to be an unusual criticism. Perhaps there are people who speak this way as adults simply because that is who they are?

First off, maybe it wasn't the best word for me to use. However, the second statement is a tautology; of course if they are childish then that is "who they are": childish people. The term to me doesn't denote an interest in "childish" things, like the CS Lewis quotation seems to say. Rather it denotes "not fully emotionally developed" which is usually a judgement placed on their current behaviour. You can read all the fairy tale books you like, I don't care. But if you start exhibiting the negative behaviours typical of children - selfishness, irresponsibility, etc - then yes, you are a bad person and deserve to be called out for it. (I'm not suggesting this at all about the author - this is now a separate discussion.)

I was reluctant to quote Lewis because there is more context to his ideas than can be conveyed in that quote. The negative behaviors you describe aren't typical of just children: they are typical of all of fallen, broken humanity. It's just that children are more honest in being direct about those negative behaviors. :)

Since we associate these negative behaviors with "childishness," we risk throwing out the good with the bad: we lose imagination, wonder, honesty, playfulness, etc.

I realize that you aren't suggesting the author has those negative behaviors. I'm only trying to provide a greater context to Lewis' quote. Perhaps I should have just stated this argument on my own; I apologize for any confusion.

Curiously, this feedback is actually making me interested in reading the Rust book. I enjoy humour and personality and wish there was more of it in business, as long as it isn't forced. (I've not read the full guide/book yet to see if it tends more towards personality or forced.)

Looking at that Julia example, I find that far too dry and academic. (The presentation is great though, better design.) For a scientific computing audience it's probably ideal, but that isn't for me.

You're not alone. On flip side, however, there are people who prefer a more informal tone and find academic treatments a little dry. I guess you can't win in that regard since someone else is bound to find your book/guide unapproachable due to whatever subjective reason they have.

That said though, I don't see why an informal tone should preclude getting the information across and sprinkling in some humor -- all without sacrificing precision. Something like Bjarne Stroustrup's C++ book is a good example of how to retain both humor and a thorough treatment of the subject.

FWIW, I agree with the previous commenter. It also makes it harder to read for those whom English is a secondary language

It makes it more fun for me to read - but significantly harder for anyone for whom English is a second language.

(I'm currently rewriting a bunch of internal documentation for offshore workers, and anything which complicates the language or is a reference to culture is being taken out, because it's just confusing to people who don't share that with you.)

Also RIP this intro: https://github.com/Gankro/rust/commit/a42a41520584e28a8fb5e4...

(one of the many reasons I refused to squash this glorious history)

Author no doubt understands programming, and the ins and outs of Rust, but has a harder time conveying his ideas in written English.

For one italics are used so much to the point of being annoying after the first 3(!) paragraphs. When something is written in italics, the reader puts more emphasis on the pronunciation of the word, lengthening the amount of time they read it for. Do this enough times and the writer starts coming across as sarcastic, and even seems to be mocking the very language constructs he is writing an advanced tutorial about!

No doubt this was not intended, and I would urge the author to take a few days off before coming back and re-reading their work, so they can try and see it from the perspective of an outsider.

> No doubt this was not intended,

I'm pretty sure the informal tone was very much intended. There's not much sarcasm there though.

Yes it is informal, but the overuse of italics makes it come across as mocking, which is what I was referring to.

I actually really enjoy the informal language, but I appreciate it's not universally loved.

Wonderful content, regardless.


Pretty good read, even if it's a draft. Only thing that bugs me a little is the informalities, and reading "That's it." after something was explained.

I apologize to ask this, but what is Rust's end game or claim to fame? It seems to a beginners eyes as if it is a new, far more complex c++.

Rust is safer than most languages (I'd argue it's even safer than Java/JS/Python/Ruby) but as fast and low-level-capable as C++. If that's not a big deal I dunno what is. (Also it has a really cool concurrency/parallelism story IMHO)

I'm not sure you can argue that Rust is far more complex if you actually understand C++ sufficiently to write correct and performant programs.

But the really great thing about Rust is that you don't actually have to understand the language to write correct and performant programs. The compiler will stop you in your tracks every time you screw up. Also there's way less performance foot-guns by default. Everything is moved instead of deep-copied by default, and you can take random pointers into things without having to worry about it.

But it's true, complicated things are complicated to express, which seems... natural to me? I dunno what people expect. But simple things are actually really simple.

For instance, here's an early version of a library I'm working on for decoding gifs: https://github.com/Gankro/gif-rs/blob/master/src/lib.rs

There isn't a single lifetime in sight. It's also really nice and readable (being able to ergonomically talk about bit and byte patterns was a big boon). Granted the library is fairly naive (it's a pull parser, but it later became clear I wanted a push parser for Servo). But I think it's a great argument for simple things are simple.

Rust gets crazy when you demand on writing extremely generic code like Hyper, because Rust leans heavily on static verification. But generic code is just always going to be cray-cray (See: Haskell lenses, C++ Boost, Scala collections).

Thanks for the link to that code, it was a pleasure to read. I then went back and read a GIF decoder I wrote some years ago in C++, code which I am very fond of -- it's pretty much the same code (as you'd expect) but my code is decorated with a lot of noise surrounding error handling and memory management/cleanup, as well as some unfortunate object oriented noise related to general style of the project it had been written for.

The things people seem to get upset about in Rust, the whole borrow checker thing, confuses me. Because often the reason the checker is complaining is because you're doing something wrong and would have a bug in another language. But because Rust brings these to the language/compiler level, vs leaving an exercise for the programmer, I suppose it looks more complicated.

I'd be surprised to hear that C++ is less complex than Rust (going by number of features or concepts or some reasonable complexity measurement).

Good point. I guess in this way C++ has a quality similar to dynamically typed languages.

It's all about total systems complexity.

For example, assembly language is very simple. It's basically just arithmetic, comparisons, i/o, and gotos, right? But building systems using assembly results in extremely complex code because it lacks the tools to manage complexity well. You end up with a rats nest of spaghetti code often, for example, unless you use structured programming macros. C++ seems "simple" but it ends up being essentially a "write-your-own-language" language with the way you can use templates, macros, and operator overrides. There's no such thing as one C++ language, there are actually hundreds of dialects that are used by different groups of people for different purposes, almost all of them effectively mutually inoperable with one another. This is a complexity nightmare.

Rust is a systems language, like C/C++, but designed from the ground up and based on modern techniques. For example, there are ways to use C++ which are particularly advantageous from a memory management aspect, such as RAII, but enforcing such uses comes down to culture/policy. Rust instead is based on different principles, specifically the idea of "borrowing", to handle memory management instead of relying on either extreme of "do what you want" or "the GC will clean up after you". There are a ton of other concepts which are baked into the Rust design which result in the ability to create programs that are easier to maintain, more likely to be correct, and more likely to be safe/secure, without sacrificing performance relative to C++ running on bare metal.

Depending on how you look at it, Rust is _far_ less complex. C++ has a _lot_ of edge cases, Rust is much more orthogonal. This is mostly due to backwards compatibility.

I was taking with someone just today about getting discriminated unions (similar to Rust's enums) into C++17 and there are just _so many_ details.

How could it possibly be more complex than C++?

In a word - "ownership". It's what makes sure you always close your files, free your memory, and avoid data races.

Rust doesn't enforce that. Recently it was shown that Rust can leak memory. Memory safety is the real thing it guarantees, without the cost of a GC. "Easy, safe, zero overhead memory management" might be a one line pitch.

I 100% agree that Rust doesn't guarantee an absence of leaks in any formal way. I dedicated a section to this fact: https://doc.rust-lang.org/nightly/adv-book/leaking.html

However I will say that Rust makes it a lot harder to accidentally leak resources (it's trivial adversarially -- but I don't consider that an interesting programming environment YMMV).

In e.g. Java you need to remember to `close` a File -- in Rust it will close itself as soon as you stop using it unless you do some wild things. We can't formally guarantee anything better than the Java scenario; it's equivalent to whoever you pass a file to having to call `close` on it.

However the defaults are reversed: In Java you don't close a File by default, and have to explicitly do something to close it. In Rust you close a File by default, and have to explicitly do something to not close it (mem::forget or Rc cycle).

This is a pretty general theme for the wins Rust provides: it picks the best default so simple things are simple, but gives you all the tools to bypass that default. By default you want to close files. By default you want to free memory. However you can leak these resources when it makes sense.

The most interesting case for me is our HashMap: we default to SipHash seeded with some OS entropy to prevent algorithmic complexity attacks. This is an explicit choice to protect our users against a relatively obscure problem. Honestly, it's probably not what most users of HashMap need. Determinism and speed is probably nicer. And yet the cost of not having that safety guard when you need it is pretty extreme.

However if you know what you're doing you can just grab a community crate with a different hasher and plug it into our HashMap. Easy as a single type annotation: https://github.com/shepmaster/twox-hash/blob/master/README.m...

"Rust can leak memory" is an overgeneralization of the issue and misrepresents it.

Rust doesn't break RAII in the usual sense. The leak issue in Rust is not something that can be cleanly talked of in the context of other languages.

In all languages with RAII till now, it's possible to "leak" memory by sending things to a permablocked thread, or stuffing them in a global hashmap, or whatever. This is something that no compiler can prevent, and it may even be desired at times.

Rust has always allowed this sort of "leaking". So have all the other languages out there.

However, Rust has the concept of scoped/borrowed data -- data with a lifetime which cannot escape that scope. Stuff that isn't scoped is said to be `'static`, i.e. it's lifetime can be the lifetime of the whole program (we can keep moving it out of functions and throwing it between threads). Scoped data can't be shoved into a global hashmap or sent to a random blocked thread, because it's not allowed to escape its scope.

Except, it turns out that using stuff like Rc cycles, it's possible to leak such data too. This affects RAII guards which use lifetimes to bind themselves to a scope to say "run destructors when this particular scope ends" (this is different from "run destructors when this object is no longer accessible", because with regular objects they can be hoisted into a larger scope by moving).

Note that the entire issue is about _scoped_ data (data with a lifetime, containing borrowed references), which is not a concept that exists in other languages.

So Rust still provides de-facto leak safety via RAII, it's just that it is possible in safe Rust to leak stuff, but you have to be explicit about it (global hashmap, mem::forget, etc). This is unlike languages where you must `delete` the object explicitly to avoid leaks.

We now have a relatively good way to describe languages based on their type story:

- untyped

- (dynamically | statically) typed

- weekly...strongly typed

Currently, we only have two terms for a language's memory story: Managed, Unmanaged. Maybe it's time to come up with some more jargon for languages based on their memory story:

- unmanaged

- (dynamically (GC) | statically) managed

- weekly...strongly managed


Where "strongly managed" is reserved for some future (if at all possible) language that can guarantee no leaks whatsoever (also it'll statically ensure halting)?

Resulting in most mainstream languages being [dynamically | weekly] managed languages, and Rust being a [statically | weekly] managed language?

I dunno.. maybe that will help with these types of discussions..

"guarantee no leaks whatsoever" isn't really possible because "leak" isn't a precise term. It depends on the _intention_ of the programmer. Shoving things in a global hashmap is desired in many cases.

FWIW it was possible to extend Rust's types with a ?Leak marker that can protect against scoped data being leaked, but that solution was not chosen.

> "Rust can leak memory" is an overgeneralization of the issue and misrepresents it.

I thought it was the exactly correct response to a comment that says Rust's main feature is that it doesn't let you leak memory. =/

It was in response to a comment that said that ownership helps deterministically close files, etc. In that context, the leakocalypse doesn't really apply.

Yes, the RAII part of ownership isn't the main feature. No, the leakocalypse is not as simple as "Rust lets you leak things"

Rust prevents memory leaks about as well as GC'd languages do. (mem::forget in Rust could easily be written in your GC'd language. Rc/Arc leaks are more of an issue, but they're pretty rare because reference counting is uncommon in Rust.)

This is great, I'll get to it when it will be in a solid state. I'm also waiting for some good high level chapters on Rust's approach to OOP and so on.

To anyone else who spots the switched around 'b' and 'c' on the repr(rust) page: don't bother, I've already created a PR.

Seeing this book is what finally got me to go through The Rust Programming Language.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact