From 10be46594da327c1f2dbf9b6582c456ef5e9fd07 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Tue, 20 Oct 2009 16:15:39 +0000 Subject: [PATCH] memroy docs --- ChangeLog | 2 +- TODO | 4 -- doc/reference/libvips-docs.sgml.in | 1 + libvips/include/vips/Makefile.am | 1 + libvips/include/vips/memory.h | 49 ++++++++++++++++++++++ libvips/include/vips/proto.h | 3 -- libvips/include/vips/util.h | 2 - libvips/include/vips/vips.h | 1 + libvips/inplace/line_draw.c | 4 +- libvips/iofuncs/memory.c | 65 ++++++++++++++++++++++++++++-- 10 files changed, 115 insertions(+), 17 deletions(-) create mode 100644 libvips/include/vips/memory.h diff --git a/ChangeLog b/ChangeLog index d5577be0..9e64cb51 100644 --- a/ChangeLog +++ b/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 diff --git a/TODO b/TODO index 8fec1e3f..bd78da35 100644 --- a/TODO +++ b/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? diff --git a/doc/reference/libvips-docs.sgml.in b/doc/reference/libvips-docs.sgml.in index 6c788d8a..5313fb1c 100644 --- a/doc/reference/libvips-docs.sgml.in +++ b/doc/reference/libvips-docs.sgml.in @@ -25,6 +25,7 @@ + diff --git a/libvips/include/vips/Makefile.am b/libvips/include/vips/Makefile.am index d036bffe..4a00c1c2 100644 --- a/libvips/include/vips/Makefile.am +++ b/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 \ diff --git a/libvips/include/vips/memory.h b/libvips/include/vips/memory.h new file mode 100644 index 00000000..5d39e779 --- /dev/null +++ b/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*/ diff --git a/libvips/include/vips/proto.h b/libvips/include/vips/proto.h index 3ffa1a76..0be8b483 100644 --- a/libvips/include/vips/proto.h +++ b/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)); diff --git a/libvips/include/vips/util.h b/libvips/include/vips/util.h index bde0bccf..2921afce 100644 --- a/libvips/include/vips/util.h +++ b/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 ) { \ diff --git a/libvips/include/vips/vips.h b/libvips/include/vips/vips.h index 78b33366..ee103051 100644 --- a/libvips/include/vips/vips.h +++ b/libvips/include/vips/vips.h @@ -123,6 +123,7 @@ typedef struct im__DOUBLEMASK { } DOUBLEMASK ; #include +#include #include #include #include diff --git a/libvips/inplace/line_draw.c b/libvips/inplace/line_draw.c index 14148897..6d93a7f9 100644 --- a/libvips/inplace/line_draw.c +++ b/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 ) || - im_incheck( ink ) || - im_copy( in, out ) ) + if( im_copy( in, out ) ) return( -1 ); mask_rect.left = mask->Xsize / 2; diff --git a/libvips/iofuncs/memory.c b/libvips/iofuncs/memory.c index 2b9bd068..6a50f65d 100644 --- a/libvips/iofuncs/memory.c +++ b/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 #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 )