memroy docs

ChangeLog

@@ -51,7 +51,7 @@
 - added im_flood_other() as start of simple segmentation operator
 - added im_segment() 
 - im_printlines(), im_debugim() deprecated (use im_vips2csv() instead)
-- meta, header, callback, error, region, check, generate gtkdocs
+- meta, header, callback, error, region, check, generate, memory gtkdocs
 - removed printlines tool, vips2csv is much better
 - removed other useless tools as well: debugim, binfile
 - fix up addr calcs on 64-bit machines with >2gb images and inplace ops

TODO

@@ -1,7 +1,3 @@
-- im_lineset() could be simpler, see im_insertplaceset()
-
-- memory.c
-
 - more stuff from util.c? too much to do it all now
 
 - how about an indexed histogram?

doc/reference/libvips-docs.sgml.in

@@ -25,6 +25,7 @@
     <xi:include href="xml/region.xml"/>
     <xi:include href="xml/generate.xml"/>
     <xi:include href="xml/error.xml"/>
+    <xi:include href="xml/memory.xml"/>
     <xi:include href="xml/buf.xml"/>
   </chapter>
 

libvips/include/vips/Makefile.am

@@ -20,6 +20,7 @@ pkginclude_HEADERS = \
 	rect.h \
 	region.h \
 	generate.h \
+	memory.h \
 	r_access.h \
 	struct.h \
 	private.h \

libvips/include/vips/memory.h

@@ -0,0 +1,49 @@
+/* memory utilities
+ *
+ * J.Cupitt, 8/4/93
+ */
+
+/*
+
+    This file is part of VIPS.
+
+    VIPS is free software; you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public License
+    along with this program; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+ */
+
+/*
+
+    These files are distributed with VIPS - http://www.vips.ecs.soton.ac.uk
+
+ */
+
+#ifndef IM_MEMORY_H
+#define IM_MEMORY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif /*__cplusplus*/
+
+#define IM_NEW( IM, T ) ((T *) im_malloc( (IM), sizeof( T )))
+#define IM_ARRAY( IM, N, T ) ((T *) im_malloc( (IM), (N) * sizeof( T )))
+
+void *im_malloc( VipsImage *im, size_t sz );
+int im_free( void * );
+
+#ifdef __cplusplus
+}
+#endif /*__cplusplus*/
+
+#endif /*IM_MEMORY_H*/

libvips/include/vips/proto.h

@@ -84,9 +84,6 @@ int im_remapfilerw( IMAGE *image );
 
 IMAGE *im_open_header( const char * );
 
-void *im_malloc( IMAGE *im, size_t sz );
-int im_free( void * );
-
 int im_cp_desc( IMAGE *, IMAGE * );
 int im_cp_descv( IMAGE *out, IMAGE *in1, ... )
 	__attribute__((sentinel));

libvips/include/vips/util.h

@@ -49,9 +49,7 @@ extern "C" {
 #define IM_ABS(x) (((x) >= 0) ? (x) : -(x))
 
 #define IM_CLIP(A,V,B) IM_MAX( (A), IM_MIN( (B), (V) ) )
-#define IM_NEW(IM,A) ((A *)im_malloc((IM),sizeof(A)))
 #define IM_NUMBER(R) ((int)(sizeof(R)/sizeof(R[0])))
-#define IM_ARRAY(IM,N,T) ((T *)im_malloc((IM),(N) * sizeof(T)))
 
 #define IM_FREEF( F, S ) do { \
         if( S ) { \

libvips/include/vips/vips.h

@@ -123,6 +123,7 @@ typedef struct im__DOUBLEMASK {
 } DOUBLEMASK ;
 
 #include <vips/image.h>
+#include <vips/memory.h>
 #include <vips/almostdeprecated.h>
 #include <vips/callback.h>
 #include <vips/error.h>

libvips/inplace/line_draw.c

@@ -430,9 +430,7 @@ im_lineset( IMAGE *in, IMAGE *out, IMAGE *mask, IMAGE *ink,
 	/* Copy the image then fastline to it ... this will render to a "t"
 	 * usually.
 	 */
-	if( im_incheck( mask ) ||
+	if( im_copy( in, out ) )
-		im_incheck( ink ) ||
-		im_copy( in, out ) )
 		return( -1 );
 
 	mask_rect.left = mask->Xsize / 2;

libvips/iofuncs/memory.c

@@ -1,4 +1,4 @@
-/* @(#) memory.c: mem handling stuff
+/* : mem handling stuff
  *
  * 2/11/99 JC
  *	- from im_open.c and callback.c
@@ -13,6 +13,8 @@
  * 	- return NULL for size <= 0
  * 11/5/06
  * 	- abort() on malloc() failure with DEBUG
+ * 20/10/09
+ * 	- gtkdoc comment
  */
 
 /*
@@ -59,6 +61,20 @@
 #include <dmalloc.h>
 #endif /*WITH_DMALLOC*/
 
+/**
+ * SECTION: memory
+ * @short_description: memory utilities
+ * @stability: Stable
+ * @include: vips/vips.h
+ *
+ * Simple memory allocation utilities. These functions and macros help
+ * allocate and free memory. Most of VIPS uses them, though some parts use
+ * the g_malloc() system instead, confusingly.
+ *
+ * If you compile with %DEBUGM it will track allocations for you, though
+ * valgrind or dmalloc are better solutions.
+ */
+
 /* Define for simple malloc tracking ... better to use dmalloc if you can.
 #define DEBUGM
  */
@@ -83,7 +99,35 @@ static const int trace_freq = 100;	/* Msg every this many malloc/free */
 static int next_trace = 0;
 #endif /*DEBUGM*/
 
-/* VIPS free function. Try to put all vips free() through this.
+/**
+ * IM_NEW:
+ * @IM: allocate memory local to @IM, or %NULL for no auto-free
+ * @T: type of thing to allocate
+ *
+ * Returns: A pointer of type @T *, or %NULL on error.
+ */
+
+/**
+ * IM_ARRAY:
+ * @IM: allocate memory local to @IM, or %NULL for no auto-free
+ * @N: number of @T 's to allocate
+ * @T: type of thing to allocate
+ *
+ * Returns: A pointer of type @T *, or %NULL on error.
+ */
+
+/**
+ * im_free:
+ * @s: memory to free
+ *
+ * VIPS free function. VIPS tries to use this instead of free(). It always
+ * returns zero, so it can be used as a callback handler. 
+ *
+ * Only use it to free
+ * memory that was previously allocated with im_malloc() with a %NULL first
+ * argument.
+ *
+ * Returns: 0
  */
 int
 im_free( void *s )
@@ -130,8 +174,21 @@ im_free( void *s )
 	return( 0 );
 }
 
-/* Malloc local to a descriptor. Try to put all vips malloc through this. Not
+/**
- * thread-safe if im != NULL.
+ * im_malloc:
+ * @im: allocate memory local to this #IMAGE, or %NULL
+ * @size: number of bytes to allocate
+ *
+ * Malloc local to @im, that is, the memory will be automatically 
+ * freed for you when the image is closed. If @im is %NULL, you need to free
+ * the memory explicitly with im_free().
+ * If allocation fails im_malloc() returns %NULL and 
+ * sets an error message.
+ *
+ * If two threads try to allocate local to the same @im at the same time, you 
+ * can get heap corruption. 
+ *
+ * Returns: a pointer to the allocated memory, or %NULL on error.
  */
 void *
 im_malloc( IMAGE *im, size_t size )