--- a/ExternalLong.st Tue Dec 07 12:27:58 2010 +0100
+++ b/ExternalLong.st Mon Dec 20 16:29:36 2010 +0100
@@ -43,19 +43,48 @@
!ExternalLong class methodsFor:'instance creation'!
new
+ "allocate some memory usable for data;
+ the memory is not controlled by the garbage collector.
+ Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).
+
+ Use this, if you have to pass a block of bytes to some
+ external destination (such as a C function) which does not copy the
+ data, but instead keeps a reference to it. For example, many functions
+ which expect strings simply keep a ref to the passed string - for those,
+ an ST/X string-pointer is not the right thing to pass, since ST/X objects
+ may change their address.
+
+ DANGER ALERT: the memory is NOT automatically freed until it is either
+ MANUALLY freed (see #free) or the returned externalBytes object
+ is unprotected or the classes releaseAllMemory method is called."
+
^ super new:4
"
ExternalLong new
"
+
+ "Modified: / 20-12-2010 / 16:22:51 / cg"
!
unprotectedNew
+ "allocate some memory usable for data;
+ the memory is under the control of the garbage collector.
+ Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).
+
+ DANGER ALERT: the memory block as allocated will be automatically freed
+ as soon as the reference to the returned externalBytes object
+ is gone (by the next garbage collect).
+ If the memory has been passed to a C-function which
+ remembers this pointer, bad things may happen ...."
+
^ super unprotectedNew:4
"
ExternalLong new
"
+
+ "Modified: / 20-12-2010 / 16:22:39 / cg"
! !
!ExternalLong methodsFor:'accessing'!
@@ -125,9 +154,9 @@
!ExternalLong class methodsFor:'documentation'!
version
- ^ '$Header: /cvs/stx/stx/libbasic2/ExternalLong.st,v 1.7 2010-07-08 14:12:50 stefan Exp $'
+ ^ '$Header: /cvs/stx/stx/libbasic2/ExternalLong.st,v 1.8 2010-12-20 15:29:36 cg Exp $'
!
version_CVS
- ^ '$Header: /cvs/stx/stx/libbasic2/ExternalLong.st,v 1.7 2010-07-08 14:12:50 stefan Exp $'
+ ^ '$Header: /cvs/stx/stx/libbasic2/ExternalLong.st,v 1.8 2010-12-20 15:29:36 cg Exp $'
! !