From 4c7b6ce2fd16231768092bd8d55c3419f69205ee Mon Sep 17 00:00:00 2001 From: Delyan Angelov Date: Sun, 7 Mar 2021 10:03:00 +0200 Subject: [PATCH] docs: expand the explanation for the `[unsafe]` fn tag --- doc/docs.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/doc/docs.md b/doc/docs.md index 3b9d4b8d8f..3b42942fce 100644 --- a/doc/docs.md +++ b/doc/docs.md @@ -4043,12 +4043,28 @@ fn bar() { foo() // will not be called if `-d debug` is not passed } -// Calls to this function must be in unsafe{} blocks +// Calls to following function must be in unsafe{} blocks. +// Note that the code in the body of `risky_business()` will still be +// checked, unless you also wrap it in `unsafe {}` blocks. +// This is usefull, when you want to have an `[unsafe]` function that +// has checks before/after a certain unsafe operation, that will still +// benefit from V's safety features. [unsafe] fn risky_business() { + // code that will be checked, perhaps checking pre conditions + unsafe { + // code that *will not be* checked, like pointer arithmetic, + // accessing union fields, calling other `[unsafe]` fns, etc... + // Usually, it is a good idea to try minimizing code wrapped + // in unsafe{} as much as possible. + // See also [Memory-unsafe code](#memory-unsafe-code) + } + // code that will be checked, perhaps checking post conditions and/or + // keeping invariants } -// V's autofree engine will not take care of memory management in this function +// V's autofree engine will not take care of memory management in this function. +// You will have the responsibility to free memory manually yourself in it. [manualfree] fn custom_allocations() { }