From 2b68f56c89667a62c0b49487ee6f54efc6be38ab Mon Sep 17 00:00:00 2001
From: Slava Pestov <slava@slava-pestovs-macbook-pro.local>
Date: Tue, 30 Mar 2010 17:31:41 -0400
Subject: [PATCH] Document (free), move it out of libc.private and mention it
 in the "c-strings" help article (reported by Blei)

---
 basis/alien/data/data-docs.factor    | 6 ++++--
 basis/cocoa/messages/messages.factor | 3 +--
 basis/libc/libc-docs.factor          | 4 ++++
 basis/libc/libc.factor               | 6 +++---
 4 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/basis/alien/data/data-docs.factor b/basis/alien/data/data-docs.factor
index 4600ea6837..d36a4d5fd2 100644
--- a/basis/alien/data/data-docs.factor
+++ b/basis/alien/data/data-docs.factor
@@ -60,6 +60,8 @@ $nl
 }
 "You must always free pointers returned by any of the above words when the block of memory is no longer in use:"
 { $subsections free }
+"The above words record memory allocations, to help catch double frees and track down memory leaks with " { $link "tools.destructors" } ". To free memory allocated by a C library, another word can be used:"
+{ $subsections (free) }
 "Utilities for automatically freeing memory in conjunction with " { $link with-destructors } ":"
 { $subsections
     &free
@@ -148,9 +150,9 @@ $nl
 }
 "The first allocates " { $link byte-array } "s, and the latter allocates manually-managed memory which is not moved by the garbage collector and has to be explicitly freed by calling " { $link free } ". See " { $link "byte-arrays-gc" } " for a discussion of the two approaches."
 $nl
-"The C type " { $link char } { $snippet "*" } " represents a generic pointer to " { $snippet "char" } "; arguments with this type will expect and return " { $link alien } "s, and won't perform any implicit string conversion."
+"The C type " { $snippet "char*" } " represents a generic pointer to " { $snippet "char" } "; arguments with this type will expect and return " { $link alien } "s, and won't perform any implicit string conversion."
 $nl
 "A word to read strings from arbitrary addresses:"
 { $subsections alien>string }
-"For example, if a C function returns a " { $link c-string } " but stipulates that the caller must deallocate the memory afterward, you must define the function as returning " { $snippet "char*" } " and call one of the above words before passing the pointer to " { $link free } "." ;
+"For example, if a C function returns a " { $link c-string } " but stipulates that the caller must deallocate the memory afterward, you must define the function as returning " { $snippet "char*" } " and call " { $link (free) } " yourself." ;
 
diff --git a/basis/cocoa/messages/messages.factor b/basis/cocoa/messages/messages.factor
index a744087037..c422d85423 100644
--- a/basis/cocoa/messages/messages.factor
+++ b/basis/cocoa/messages/messages.factor
@@ -5,8 +5,7 @@ classes.struct continuations combinators compiler compiler.alien
 core-graphics.types stack-checker kernel math namespaces make
 quotations sequences strings words cocoa.runtime cocoa.types io
 macros memoize io.encodings.utf8 effects layouts libc
-libc.private lexer init core-foundation fry generalizations
-specialized-arrays ;
+lexer init core-foundation fry generalizations specialized-arrays ;
 QUALIFIED-WITH: alien.c-types c
 IN: cocoa.messages
 
diff --git a/basis/libc/libc-docs.factor b/basis/libc/libc-docs.factor
index b89f4174bf..74e96b08d3 100644
--- a/basis/libc/libc-docs.factor
+++ b/basis/libc/libc-docs.factor
@@ -32,6 +32,10 @@ HELP: free
 { $values { "alien" c-ptr } }
 { $description "Deallocates a block of memory allocated by " { $link malloc } ", " { $link calloc } " or " { $link realloc } "." } ;
 
+HELP: (free)
+{ $values { "alien" c-ptr } }
+{ $description "Deallocates a block of memory allocated by an external C library." } ;
+
 HELP: &free
 { $values { "alien" c-ptr } }
 { $description "Marks the block of memory for unconditional deallocation at the end of the current " { $link with-destructors } " scope." } ;
diff --git a/basis/libc/libc.factor b/basis/libc/libc.factor
index 5f6a808b2e..4a887e695f 100644
--- a/basis/libc/libc.factor
+++ b/basis/libc/libc.factor
@@ -1,5 +1,5 @@
 ! Copyright (C) 2004, 2005 Mackenzie Straight
-! Copyright (C) 2007, 2009 Slava Pestov
+! Copyright (C) 2007, 2010 Slava Pestov
 ! Copyright (C) 2007, 2008 Doug Coleman
 ! See http://factorcode.org/license.txt for BSD license.
 USING: alien alien.c-types assocs continuations alien.destructors kernel
@@ -18,8 +18,6 @@ IN: libc
 : preserve-errno ( quot -- )
     errno [ call ] dip set-errno ; inline
 
-<PRIVATE
-
 : (malloc) ( size -- alien )
     void* "libc" "malloc" { ulong } alien-invoke ;
 
@@ -32,6 +30,8 @@ IN: libc
 : (realloc) ( alien size -- newalien )
     void* "libc" "realloc" { void* ulong } alien-invoke ;
 
+<PRIVATE
+
 ! We stick malloc-ptr instances in the global disposables set
 TUPLE: malloc-ptr value continuation ;