Skip to content

Commit a22e290

Browse files
committed
Elaborate on how to use an extern static correctly
1 parent e115753 commit a22e290

File tree

1 file changed

+12
-1
lines changed

1 file changed

+12
-1
lines changed

src/items/external-blocks.md

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,8 @@ Two kind of item _declarations_ are allowed in external blocks: [functions] and
3838
[statics]. Calling functions or accessing statics that are declared in external
3939
blocks is only allowed in an `unsafe` context.
4040

41+
## Functions
42+
4143
Functions within external blocks are declared in the same way as other Rust
4244
functions, with the exception that they may not have a body and are instead
4345
terminated by a semicolon. Patterns are not allowed in parameters, only
@@ -53,10 +55,19 @@ extern "abi" for<'l1, ..., 'lm> fn(A1, ..., An) -> R`, where `'l1`, ... `'lm`
5355
are its lifetime parameters, `A1`, ..., `An` are the declared types of its
5456
parameters and `R` is the declared return type.
5557

58+
## Statics
59+
5660
Statics within external blocks are declared in the same way as statics outside of external blocks,
5761
except that they do not have an expression initializing their value.
5862
It is `unsafe` to access a static item declared in an extern block, whether or
59-
not it's mutable.
63+
not it's mutable, because there is nothing guaranteeing that the bit pattern at the static's
64+
memory is valid for the type it is declared with, since some arbitrary (e.g. C) code is in charge
65+
of initializing the static.
66+
67+
Extern statics can be either immutable or mutable just like statics outside of external blocks.
68+
An immutable static *must* be initialized before any Rust code is executed. It is not enough for
69+
the static to be initialized before Rust code reads from it. This may change in the future, but for
70+
now, if you want to lazily initialize such a static, use a mutable static.
6071

6172
## ABI
6273

0 commit comments

Comments
 (0)