Document that CStrings live in the libc heap

Insists on the fact that the memory is managed by malloc
and not jemalloc
Closes #17067

diff --git a/src/librustrt/c_str.rs b/src/librustrt/c_str.rs
index 5e0004f2a2a3e04861cf4d1f8d6b5c1bff09bb03..2390dcff3af71c19c26f42b5eb143bba0aff42ea 100644 (file)
--- a/src/librustrt/c_str.rs
+++ b/src/librustrt/c_str.rs
@@ -36,6 +36,11 @@
 heavily used in applications, then caching may be advisable to prevent
 unnecessary amounts of allocations.
 
 heavily used in applications, then caching may be advisable to prevent
 unnecessary amounts of allocations.
 

+Be carefull to remember that the memory is managed by libc's malloc and not
+by jemalloc which is the 'normal' rust memory allocator.
+That means that the CString pointers should only be freed with 
+alloc::libc_heap::malloc_raw if you intend to do that on your own.
+

 An example of creating and using a C string would be:
 
 ```rust
 An example of creating and using a C string would be:
 
 ```rust


@@ -91,8 +96,8 @@ pub struct CString {
 
 impl Clone for CString {
     /// Clone this CString into a new, uniquely owned CString. For safety
 
 impl Clone for CString {
     /// Clone this CString into a new, uniquely owned CString. For safety

-    /// reasons, this is always a deep clone, rather than the usual shallow
-    /// clone.
+    /// reasons, this is always a deep clone with the memory allocated
+    /// with libc's malloc, rather than the usual shallow clone.

     fn clone(&self) -> CString {
         let len = self.len() + 1;
         let buf = unsafe { malloc_raw(len) } as *mut libc::c_char;
     fn clone(&self) -> CString {
         let len = self.len() + 1;
         let buf = unsafe { malloc_raw(len) } as *mut libc::c_char;


@@ -131,7 +136,8 @@ fn hash(&self, state: &mut S) {
 }
 
 impl CString {
 }
 
 impl CString {

-    /// Create a C String from a pointer.
+    /// Create a C String from a pointer, with memory managed by libc's malloc,
+    /// so do not call it with a pointer allocated by jemalloc.

     ///
     ///# Failure
     ///
     ///
     ///# Failure
     ///


@@ -265,7 +271,8 @@ pub fn iter<'a>(&'a self) -> CChars<'a> {
     /// forgotten, meaning that the backing allocation of this
     /// `CString` is not automatically freed if it owns the
     /// allocation. In this case, a user of `.unwrap()` should ensure
     /// forgotten, meaning that the backing allocation of this
     /// `CString` is not automatically freed if it owns the
     /// allocation. In this case, a user of `.unwrap()` should ensure

-    /// the allocation is freed, to avoid leaking memory.
+    /// the allocation is freed, to avoid leaking memory. You have to
+    /// use libc's memory allocator in this case.

     ///
     /// Prefer `.as_ptr()` when just retrieving a pointer to the
     /// string data, as that does not relinquish ownership.
     ///
     /// Prefer `.as_ptr()` when just retrieving a pointer to the
     /// string data, as that does not relinquish ownership.