roc-lang/roc
1
1
Fork 0
mirror of https://github.com/roc-lang/roc.git synced 2024-09-21 07:49:17 +03:00
Code Issues Packages Projects Releases Wiki Activity

expand safety doc comment

Browse Source
This commit is contained in:
Brendan Hansknecht 2022-10-19 12:09:05 -07:00
parent 6ebfcc8fa1
commit 8804b28be0
No known key found for this signature in database
GPG Key ID: 0EA784685083E75B
2 changed files with 28 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
crates/roc_std/src/roc_list.rs
View File

@ -121,9 +121,20 @@ impl<T> RocList<T> {
}
}
// Marks a list as readonly. This means that it will be leaked.
// For constants passed in from platform to application, this may be reasonable.
// Marked unsafe because it should not be used lightly.
/// Marks a list as readonly. This means that it will be leaked.
/// For constants passed in from platform to application, this may be reasonable.
///
/// # Safety
///
/// A value can be read-only in Roc for 3 reasons:
/// 1. The value is stored in read-only memory like a constant in the app.
/// 2. Our refcounting maxes out. When that happens, we saturate to read-only.
/// 3. This function is called
///
/// Any value that is set to read-only will be leaked.
/// There is no way to tell how many references it has and if it is safe to free.
/// As such, only values that should have a static lifetime for the entire application run
/// should be considered for marking read-only.
pub unsafe fn set_readonly(&self) {
if let Some((_, storage)) = self.elements_and_storage() {
storage.set(Storage::Readonly);

17
crates/roc_std/src/roc_str.rs
View File

@ -123,9 +123,20 @@ impl RocStr {
}
}
// Marks a str as readonly. This means that it will be leaked.
// For constants passed in from platform to application, this may be reasonable.
// Marked unsafe because it should not be used lightly.
/// Marks a str as readonly. This means that it will be leaked.
/// For constants passed in from platform to application, this may be reasonable.
///
/// # Safety
///
/// A value can be read-only in Roc for 3 reasons:
/// 1. The value is stored in read-only memory like a constant in the app.
/// 2. Our refcounting maxes out. When that happens, we saturate to read-only.
/// 3. This function is called
///
/// Any value that is set to read-only will be leaked.
/// There is no way to tell how many references it has and if it is safe to free.
/// As such, only values that should have a static lifetime for the entire application run
/// should be considered for marking read-only.
pub unsafe fn set_readonly(&self) {
match self.as_enum_ref() {
RocStrInnerRef::HeapAllocated(roc_list) => unsafe { roc_list.set_readonly() },