From a22e290a05d9f4f46b244f6e5ebf05bc5f8dbfa1 Mon Sep 17 00:00:00 2001 From: Oliver Scherer Date: Thu, 9 Jan 2020 16:39:23 +0100 Subject: [PATCH 1/3] Elaborate on how to use an extern static correctly --- src/items/external-blocks.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 211a2fa4c..01dfe7f13 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -38,6 +38,8 @@ Two kind of item _declarations_ are allowed in external blocks: [functions] and [statics]. Calling functions or accessing statics that are declared in external blocks is only allowed in an `unsafe` context. +## Functions + Functions within external blocks are declared in the same way as other Rust functions, with the exception that they may not have a body and are instead 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` are its lifetime parameters, `A1`, ..., `An` are the declared types of its parameters and `R` is the declared return type. +## Statics + Statics within external blocks are declared in the same way as statics outside of external blocks, except that they do not have an expression initializing their value. It is `unsafe` to access a static item declared in an extern block, whether or -not it's mutable. +not it's mutable, because there is nothing guaranteeing that the bit pattern at the static's +memory is valid for the type it is declared with, since some arbitrary (e.g. C) code is in charge +of initializing the static. + +Extern statics can be either immutable or mutable just like statics outside of external blocks. +An immutable static *must* be initialized before any Rust code is executed. It is not enough for +the static to be initialized before Rust code reads from it. This may change in the future, but for +now, if you want to lazily initialize such a static, use a mutable static. ## ABI From 53d0cec97e4d0649e6e43523232f69e626c49723 Mon Sep 17 00:00:00 2001 From: Oliver Scherer Date: Fri, 10 Jan 2020 11:39:41 +0100 Subject: [PATCH 2/3] Remove user advice --- src/items/external-blocks.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 01dfe7f13..60bbdc269 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -66,8 +66,7 @@ of initializing the static. Extern statics can be either immutable or mutable just like statics outside of external blocks. An immutable static *must* be initialized before any Rust code is executed. It is not enough for -the static to be initialized before Rust code reads from it. This may change in the future, but for -now, if you want to lazily initialize such a static, use a mutable static. +the static to be initialized before Rust code reads from it. ## ABI From 18d7140a96d3d898ccded0cc32a16675681b0846 Mon Sep 17 00:00:00 2001 From: Oliver Scherer Date: Fri, 10 Jan 2020 11:40:44 +0100 Subject: [PATCH 3/3] Add links to statics chapter --- src/items/external-blocks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/items/external-blocks.md b/src/items/external-blocks.md index 60bbdc269..7acb5ce3c 100644 --- a/src/items/external-blocks.md +++ b/src/items/external-blocks.md @@ -57,14 +57,14 @@ parameters and `R` is the declared return type. ## Statics -Statics within external blocks are declared in the same way as statics outside of external blocks, +Statics within external blocks are declared in the same way as [statics] outside of external blocks, except that they do not have an expression initializing their value. It is `unsafe` to access a static item declared in an extern block, whether or not it's mutable, because there is nothing guaranteeing that the bit pattern at the static's memory is valid for the type it is declared with, since some arbitrary (e.g. C) code is in charge of initializing the static. -Extern statics can be either immutable or mutable just like statics outside of external blocks. +Extern statics can be either immutable or mutable just like [statics] outside of external blocks. An immutable static *must* be initialized before any Rust code is executed. It is not enough for the static to be initialized before Rust code reads from it.