mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Guide: unsafe

Browse Source
This commit is contained in:
Steve Klabnik 2014-08-07 18:17:57 -04:00
parent 1681f43b91
commit 139516685b
1 changed files with 150 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
src/doc/guide.md
View File

@ -535,7 +535,7 @@ arguments we pass to functions and macros, if you're passing more than one.
When you just use the curly braces, Rust will attempt to display the
value in a meaningful way by checking out its type. If you want to specify the
format in a more detailed manner, there are a [wide number of options
available](/std/fmt/index.html). For now, we'll just stick to the default:
available](std/fmt/index.html). For now, we'll just stick to the default:
integers aren't very complicated to print.
So, we've cleared up all of the confusion around bindings, with one exception:
@ -3520,15 +3520,15 @@ out.
In systems programming, pointers are an incredibly important topic. Rust has a
very rich set of pointers, and they operate differently than in many other
languages. They are important enough that we have a specific [Pointer
Guide](/guide-pointers.html) that goes into pointers in much detail. In fact,
Guide](guide-pointers.html) that goes into pointers in much detail. In fact,
while you're currently reading this guide, which covers the language in broad
overview, there are a number of other guides that put a specific topic under a
microscope. You can find the list of guides on the [documentation index
page](/index.html#guides).
page](index.html#guides).
In this section, we'll assume that you're familiar with pointers as a general
concept. If you aren't, please read the [introduction to
pointers](/guide-pointers.html#an-introduction) section of the Pointer Guide,
pointers](guide-pointers.html#an-introduction) section of the Pointer Guide,
and then come back here. We'll wait.
Got the gist? Great. Let's talk about pointers in Rust.
@ -4711,75 +4711,177 @@ fail.
# Macros
One of Rust's most advanced features is is system of **macro**s. While
One of Rust's most advanced features is its system of **macro**s. While
functions allow you to provide abstractions over values and operations, macros
allow you to provide abstractions over syntax. Do you wish Rust had the ability
to do something that it can't currently do? You may be able to write a macro
to extend Rust's capabilities.
You've already used one macro extensively: `println!`. When we invoke
You've already used one macro extensively: `println!`. When we invoke
a Rust macro, we need to use the exclamation mark (`!`). There's two reasons
that this is true: the first is that it makes it clear when you're using a
macro. The second is that macros allow for flexible syntax, and so Rust must
be able to tell where a macro starts and ends. The `!(...)` helps with this.
An example of even more advanced macro usage is in Rust's `regex` crate. This
implements **regular expressions* for Rust. Regular expressions provide a
powerful way to determine if a string matches a certain pattern, but they also
have their own syntax. Therefore, they're a perfect fit for Rust's macros.
Here's an example of using a regular expression in Rust:
Let's talk some more about `println!`. We could have implemented `println!` as
a function, but it would be worse. Why? Well, what macros allow you to do
is write code that generates more code. So when we call `println!` like this:
```{rust}
#![feature(phase)]
#[phase(plugin)]
extern crate regex_macros;
extern crate regex;
let x = 5i;
println!("x is: {}", x);
```
The `println!` macro does a few things:
1. It parses the string to find any `{}`s
2. It checks that the number of `{}`s matches the number of other arguments.
3. It generates a bunch of Rust code, taking this in mind.
What this means is that you get type checking at compile time, because
Rust will generate code that takes all of the types into account. If
`println!` was a function, it could still do this type checking, but it
would happen at run time rather than compile time.
We can check this out using a special flag to `rustc`. This code, in a file
`print.rs`:
```{rust}
fn main() {
let re = regex!(r"^\d{4}-\d{2}-\d{2}$");
println!("Does our expression match? {}", re.is_match("2014-01-01"));
let x = "Hello";
println!("x is: {:s}", x);
}
```
This will print "Does our expression match? true". Now, we won't learn
everything there is to know about regular expressions in this tutorial. We can
consult [the regex crate's documentation](/regex/index.html) for more on that
later. For now, here's the important parts:
Can have its macros expanded like this: `rustc print.rs --pretty=expanded`, will
give us this huge result:
```{rust}
```{rust,ignore}
#![feature(phase)]
#[phase(plugin)]
extern crate regex_macros;
# fn main() {}
#![no_std]
#![feature(globs)]
#[phase(plugin, link)]
extern crate std = "std";
extern crate rt = "native";
use std::prelude::*;
fn main() {
let x = "Hello";
match (&x,) {
(__arg0,) => {
#[inline]
#[allow(dead_code)]
static __STATIC_FMTSTR: [::std::fmt::rt::Piece<'static>, ..2u] =
[::std::fmt::rt::String("x is: "),
::std::fmt::rt::Argument(::std::fmt::rt::Argument{position:
::std::fmt::rt::ArgumentNext,
format:
::std::fmt::rt::FormatSpec{fill:
' ',
align:
::std::fmt::rt::AlignUnknown,
flags:
0u,
precision:
::std::fmt::rt::CountImplied,
width:
::std::fmt::rt::CountImplied,},})];
let __args_vec =
&[::std::fmt::argument(::std::fmt::secret_string, __arg0)];
let __args =
unsafe {
::std::fmt::Arguments::new(__STATIC_FMTSTR, __args_vec)
};
::std::io::stdio::println_args(&__args)
}
};
}
```
These attributes allow the `regex_macros` crate to actually hook in to the
compiler itself and extend it with the regular expression syntax. Macros
are serious business!
Intense. Here's a trimmed down version that's a bit easier to read:
Next, let's look at the actual invocation:
```{rust,ignore}
fn main() {
let x = 5i;
match (&x,) {
(__arg0,) => {
static __STATIC_FMTSTR: =
[String("x is: "),
Argument(Argument {
position: ArgumentNext,
format: FormatSpec {
fill: ' ',
align: AlignUnknown,
flags: 0u,
precision: CountImplied,
width: CountImplied,
},
},
];
let __args_vec = &[argument(secret_string, __arg0)];
let __args = unsafe { Arguments::new(__STATIC_FMTSTR, __args_vec) };
```{rust}
# #![feature(phase)]
# #[phase(plugin)]
# extern crate regex_macros;
# extern crate regex;
# fn main() {
let re = regex!(r"^\d{4}-\d{2}-\d{2}$");
# }
println_args(&__args)
}
};
}
```
The `regex!` macro allows us to define a macro. inside of the `()`s, we have a
`r""` construct. This is a 'raw' string literal, that does no escaping of its
contents. This is a Rust feature, not a macros feature. Finally, the rest of
the insides, which is the regular expression itself. This regular expression
roughly translates to "four digits, followed by a hypen, followed by two
digits, followed by a hypen, followed by two digits."
Whew! This isn't too terrible. You can see that we still `let x = 5i`,
but then things get a little bit hairy. Three more bindings get set: a
static format string, an argument vector, and the aruments. We then
invoke the `println_args` function with the generated arguments.
For more on macros, please consult [the Macros Guide](/guide-macros.html).
Macros are a very advanced and still slightly experimental feature, and don't
require a deep understanding to use. The Guide can help you if you want to
write your own.
This is the code (well, the full version) that Rust actually compiles. You can
see all of the extra information that's here. We get all of the type safety and
options that it provides, but at compile time, and without needing to type all
of this out. This is how macros are powerful. Without them, you would need to
type all of this by hand to get a type checked `println`.
For more on macros, please consult [the Macros Guide](guide-macros.html).
Macros are a very advanced and still slightly experimental feature, but don't
require a deep understanding to call, since they look just like functions. The
Guide can help you if you want to write your own.
# Unsafe
Finally, there's one more concept that you should be aware in Rust: `unsafe`.
There are two circumstances where Rust's safety provisions don't work well.
The first is when interfacing with C code, and the second is when building
certain kinds of abstractions.
Rust has support for FFI, (which you can read about in the [FFI
Guide](guide-ffi.html)) but Rust can't guarantee that the C code will be safe,
like Rust's will. Therefore, Rust marks such functions with the `unsafe`
keyword, which indicates that the function may not behave properly.
Second, if you'd like to create some sort of shared-memory data structure, Rust
won't allow it, because memory must be owned by a single owner. However, if
you're planning on making access to that shared memory safe, such as with a
mutex, _you_ know that it's safe, but Rust can't know. Writing an `unsafe`
block allows you to ask the compiler to trust you. In this case, the _internal_
implementation of the mutex is considered unsafe, but the _external_ interface
we present is safe. This allows it to be effectively used in normal Rust, while
being able to implement functionality that the compiler can't double check for
us.
Doesn't an escape hatch undermine the safety of the entire system? Well, if
Rust code segfaults, it _must_ be because of unsafe code somewhere. By
annotating exactly where that is, you have a significantly smaller area to
search.
We haven't even talked about any examples here, and that's because I want to
emphasize that you should not be writing unsafe code unless you know exactly
what you're doing. The vast majority of Rust developers will only interact with
it when doing FFI, and advanced library authors may use it to build certain
kinds of abstraction.
# Conclusion
We covered a lot of ground here. When you've mastered everything in this Guide,
you will have a firm grasp of basic Rust development. There's a whole lot more
out there, we've just covered the surface. There's tons of topics that you can
dig deeper into, and we've built specialized guides for many of them. To learn
more, dig into the [full documentation
index](http://doc.rust-lang.org/index.html).
Happy hacking!