added invaliidate callbacks

ChangeLog

@@ -28,6 +28,7 @@
   accidents on some platforms
 - configure prints a summary of optional packages found at the end
 - im_lhisteq() checks for window too small
+- added invalidate callbacks
 
 25/1/08 started 7.14.0
 - bump all version numbers for new stable

doc/src/pio.tex

@@ -797,7 +797,8 @@ full details.
 \label{sec:callback}
 
 VIPS lets you attach callbacks to image descriptors. These are functions
-you provide that VIPS will call when certain events occur. 
+you provide that VIPS will call when certain events occur. There are more
+callbacks than are listed here: see the man page for full details.
 
 \subsubsection{Close callbacks}
 

include/vips/proto.h

@@ -157,6 +157,7 @@ int im_add_preclose_callback( IMAGE *, im_callback_fn, void *, void * );
 int im_add_evalstart_callback( IMAGE *, im_callback_fn, void *, void * );
 int im_add_eval_callback( IMAGE *, im_callback_fn, void *, void * );
 int im_add_evalend_callback( IMAGE *, im_callback_fn, void *, void * );
+int im_add_invalidate_callback( IMAGE *, im_callback_fn, void *, void * );
 
 void error_exit( const char *, ... )
 	__attribute__((noreturn, format(printf, 1, 2)));

include/vips/vips.h

@@ -38,6 +38,8 @@
  * 7/11/07
  * 	- added preclose and evalstart callbacks
  * 	- brought time struct in here
+ * 2/7/08
+ * 	- added invalidate callbacks
  */
 
 /*
@@ -339,6 +341,7 @@ typedef struct im__IMAGE {
 	 */
 	GSList *evalstartfns; 	/* list of start eval callbacks */
 	GSList *preclosefns; 	/* list of pre-close callbacks */
+	GSList *invalidatefns; 	/* list of invalidate callbacks */
 } IMAGE;
 
 /* Only define if IM_ENABLE_DEPRECATED is set.

libsrc/iofuncs/buffer.c

@@ -563,6 +563,8 @@ im_invalidate_image( IMAGE *im )
 {
 	(void) im_slist_map2( im->regions,
 		(VSListMap2Fn) im_invalidate_region, NULL, NULL );
+	if( im__trigger_callbacks( im->invalidatefns ) )
+		return( im );
 
 	return( NULL );
 }

man/Makefile.am

@@ -25,6 +25,7 @@ man_MANS = \
 	im_add_evalstart_callback.3 \
 	im_add_eval_callback.3 \
 	im_add_evalend_callback.3 \
+	im_add_invalidate_callback.3 \
 	im_addgnoise.3 \
 	im_affine.3 \
 	im_allocate_input_array.3 \

man/im_add_invalidate_callback.3

@@ -0,0 +1 @@
+.so man3/im_malloc.3

man/im_invalidate.3

@@ -12,5 +12,8 @@ marks all caches related to the image as invalid and requring recalculation.
 It needs to be called if an image changes after being made: for example, after
 a paint action, or perhaps after a new frame has arrived from a video source.
 
+Any invalidate callbacks registered on any of the affected images are
+triggered.
+
 .SH SEE\ ALSO
-im_prepare(3), im_region_buffer(3).
+im_prepare(3), im_region_buffer(3), im_add_invalidate_callback(3).

man/im_malloc.3

@@ -1,7 +1,8 @@
 .TH IM_AND 3 "30 October 1992"
 .SH NAME
 im_add_close_callback, im_add_eval_callback, im_malloc, im_free,
-im_add_evalend_callback, im_add_evalstart_callback, im_add_preclose_callback \- add image callbacks
+im_add_evalend_callback, im_add_evalstart_callback, im_add_preclose_callback,
+im_add_invalidate_callback \- add image callbacks
 .SH SYNOPSIS
 .B #include <vips/vips.h>
 
@@ -17,6 +18,8 @@ int im_add_eval_callback( IMAGE *, im_callback_fn, void *, void * );
 
 int im_add_evalend_callback( IMAGE *, im_callback_fn, void *, void * );
 
+int im_add_invalidate_callback( IMAGE *, im_callback_fn, void *, void * );
+
 void *im_malloc( IMAGE *, size_t );
 
 int im_free( void * );
@@ -136,6 +139,10 @@ has finished evaluating the image. If you want to output some diagnostics
 from your function (an overflow count, for example), this is the callback to
 use. Again, this can be called many times. 
 
+.B im_add_invalidate_callback(3) 
+adds a callback which will be triggered when VIPS invalidates the cache on an
+image. This is useful for removing images from other, higher-level caches.
+
 .SH RETURN VALUE
 All functions return 0 on success and non-zero on error.
 .SH SEE ALSO