From b6cb3cbcbd75a77e225632807d2ee6f739fc0aa3 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Fri, 2 Oct 2009 10:22:16 +0000 Subject: [PATCH] add callback gtkdoc --- ChangeLog | 1 + doc/reference/libvips-docs.sgml.in | 1 + libvips/include/vips/Makefile.am | 1 + libvips/include/vips/callback.h | 56 ++++++++++ libvips/include/vips/proto.h | 7 -- libvips/include/vips/util.h | 1 - libvips/include/vips/vips.h | 1 + libvips/iofuncs/callback.c | 159 +++++++++++++++++++++++++++-- libvips/iofuncs/meta.c | 2 +- 9 files changed, 210 insertions(+), 19 deletions(-) create mode 100644 libvips/include/vips/callback.h diff --git a/ChangeLog b/ChangeLog index 6267298b..786a6bb9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -53,6 +53,7 @@ - gtk-doc comments for meta - gtk-doc comments for header - im_printlines(), im_debugim() deprecated (use im_vips2csv() instead) +- callback gtkdocs 25/3/09 started 7.18.0 - revised version numbers diff --git a/doc/reference/libvips-docs.sgml.in b/doc/reference/libvips-docs.sgml.in index 74fe29b4..b14df8c6 100644 --- a/doc/reference/libvips-docs.sgml.in +++ b/doc/reference/libvips-docs.sgml.in @@ -19,6 +19,7 @@ Core VIPS API + diff --git a/libvips/include/vips/Makefile.am b/libvips/include/vips/Makefile.am index 84111558..21d59ae7 100644 --- a/libvips/include/vips/Makefile.am +++ b/libvips/include/vips/Makefile.am @@ -7,6 +7,7 @@ pkginclude_HEADERS = \ dispatch.h \ format.h \ header.h \ + callback.h \ fmask.h \ mosaic.h \ interpolate.h \ diff --git a/libvips/include/vips/callback.h b/libvips/include/vips/callback.h new file mode 100644 index 00000000..e130e2d8 --- /dev/null +++ b/libvips/include/vips/callback.h @@ -0,0 +1,56 @@ +/* Various callbacks. + */ + +/* + + Copyright (C) 1991-2005 The National Gallery + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU 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 General Public License for more details. + + You should have received a copy of the GNU 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_CALLBACK_H +#define IM_CALLBACK_H + +#ifdef __cplusplus +extern "C" { +#endif /*__cplusplus*/ + +/* Also used for eg. im_local() and friends. + */ +typedef int (*im_callback_fn)( void *a, void *b ); + +int im_add_close_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ); +int im_add_preclose_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ); + +int im_add_evalstart_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ); +int im_add_eval_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ); +int im_add_evalend_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ); + +int im_add_invalidate_callback( IMAGE *im, + im_callback_fn fn, void *a, void *b ); + + +#ifdef __cplusplus +} +#endif /*__cplusplus*/ + +#endif /*!IM_CALLBACK_H*/ diff --git a/libvips/include/vips/proto.h b/libvips/include/vips/proto.h index 1a03fb67..eb9ca278 100644 --- a/libvips/include/vips/proto.h +++ b/libvips/include/vips/proto.h @@ -146,13 +146,6 @@ int im_existsf( const char *name, ... ) __attribute__((format(printf, 1, 2))); int im_isvips( const char * ); -int im_add_close_callback( IMAGE *, im_callback_fn, void *, void * ); -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))); const char *im_error_buffer( void ); diff --git a/libvips/include/vips/util.h b/libvips/include/vips/util.h index b54da355..b711b1db 100644 --- a/libvips/include/vips/util.h +++ b/libvips/include/vips/util.h @@ -181,7 +181,6 @@ extern "C" { /* Basic function types. */ -typedef int (*im_callback_fn)( void *, void * ); typedef void *(*im_construct_fn)( void *, void *, void * ); /* strtok replacement. diff --git a/libvips/include/vips/vips.h b/libvips/include/vips/vips.h index 315e9bfb..5d29b93a 100644 --- a/libvips/include/vips/vips.h +++ b/libvips/include/vips/vips.h @@ -124,6 +124,7 @@ typedef struct im__DOUBLEMASK { #include #include +#include #include #include /* #include */ diff --git a/libvips/iofuncs/callback.c b/libvips/iofuncs/callback.c index 365118fa..2808fe19 100644 --- a/libvips/iofuncs/callback.c +++ b/libvips/iofuncs/callback.c @@ -54,13 +54,28 @@ #include #endif /*WITH_DMALLOC*/ +/** + * SECTION: callback + * @short_description: image callbacks + * @stability: Stable + * @see_also: image + * @include: vips/vips.h + * + * Images trigger various callbacks at various points in their lifetime. You + * can register callbacks and be notified of various events, such as + * evaluation progress or close. + * + * Callbacks should return 0 for success, or -1 on error, setting an error + * message with im_error(). + */ + /* Callback struct. We attach a list of callbacks to images to be invoked when * the image is closed. These do things like closing previous elements in a * chain of operations, freeing client data, etc. */ typedef struct { IMAGE *im; /* IMAGE we are attached to */ - int (*fn)(); /* callback function */ + im_callback_fn fn; /* callback function */ void *a, *b; /* arguments to callback */ } VCallback; @@ -68,7 +83,7 @@ typedef struct { * im__close(), or by im_generate(), etc. for evalend callbacks. */ static int -add_callback( IMAGE *im, GSList **cblist, int (*fn)(), void *a, void *b ) +add_callback( IMAGE *im, GSList **cblist, im_callback_fn fn, void *a, void *b ) { VCallback *cbs; @@ -84,23 +99,81 @@ add_callback( IMAGE *im, GSList **cblist, int (*fn)(), void *a, void *b ) return( 0 ); } +/** + * im_add_close_callback: + * @im: image to attach callback to + * @fn: callback function + * @a: user data 1 + * @b: user data 2 + * + * Attaches a close callback @fn to @im. + * + * Close callbacks are triggered exactly once when the image has been closed + * and most resources freed, but just before the memory for @im is released. + * + * Close callbacks are a good place to free memory that was need to generate + * @im, delete temporary files and so on. You can close other images and there + * may even be circularity in your close lists. + * + * See also: im_malloc() (implemented with im_add_close_callback()), + * im_add_preclose_callback() (called earlier in the image close process), + * im_free(). + */ int -im_add_close_callback( IMAGE *im, int (*fn)(), void *a, void *b ) +im_add_close_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ) { return( add_callback( im, &im->closefns, fn, a, b ) ); } +/** + * im_add_preclose_callback: + * @im: image to attach callback to + * @fn: callback function + * @a: user data 1 + * @b: user data 2 + * + * Attaches a pre-close callback @fn to @im. + * + * Pre-close callbacks are triggered exactly once just before an image is + * closed. The image is still valid and you can do anything with it, except + * stop close from happening. + * + * Pre-close callbacks are a good place for languae bindings to break as + * association between the language object and the VIPS image. + */ int -im_add_preclose_callback( IMAGE *im, int (*fn)(), void *a, void *b ) +im_add_preclose_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ) { return( add_callback( im, &im->preclosefns, fn, a, b ) ); } -/* Add an eval callback to an IMAGE. You must call this after opening the - * image but before using it as an argument to an operation. +/** + * im_add_eval_callback: + * @im: image to attach callback to + * @fn: callback function + * @a: user data 1 + * @b: user data 2 + * + * Attaches an eval callback @fn to @im. + * + * Eval callbacks are called during evaluation and are a good place to give + * the user feedback about computation progress. In the eval callback, you may + * look at the #VipsProgress #time member of #IMAGE to get information about + * the number of + * pels processed, elapsed time, and so on. + * + * Eval callbacks are inherited. That is, any images which use your image + * as input will inherit your eval callbacks. As a result, if you add an + * eval callback to an image, you will be notified if any later image uses + * your image for computation. + * + * If a later image adds eval callbacks, then the inheritance is broken, + * and that image will recieve notification instead. + * + * See also: im_add_evalend_callback(), im_add_evalstart_callback(). */ int -im_add_eval_callback( IMAGE *im, int (*fn)(), void *a, void *b ) +im_add_eval_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ) { /* Mark this image as needing progress feedback. im__link_make() * propogates this value to our children as we build a pipeline. @@ -111,20 +184,86 @@ im_add_eval_callback( IMAGE *im, int (*fn)(), void *a, void *b ) return( add_callback( im, &im->evalfns, fn, a, b ) ); } +/** + * im_add_evalend_callback: + * @im: image to attach callback to + * @fn: callback function + * @a: user data 1 + * @b: user data 2 + * + * Attaches an eval end callback @fn to @im. + * + * Eval end callbacks are called at the end of evaluation. They are a good + * place to clean up after progress notification or to display some + * diagnostics about computation (eg. an overflow count). They can be called + * many times. Every evalend call is guaranteed to have a matching evalstart, + * but not necessarily any eval calls. + * + * Eval callbacks are inherited. That is, any images which use your image + * as input will inherit your eval callbacks. As a result, if you add an + * eval callback to an image, you will be notified if any later image uses + * your image for computation. + * + * If a later image adds eval callbacks, then the inheritance is broken, + * and that image will recieve notification instead. + * + * See also: im_add_eval_callback(), im_add_evalstart_callback(). + */ int -im_add_evalend_callback( IMAGE *im, int (*fn)(), void *a, void *b ) +im_add_evalend_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ) { return( add_callback( im, &im->evalendfns, fn, a, b ) ); } +/** + * im_add_evalstart_callback: + * @im: image to attach callback to + * @fn: callback function + * @a: user data 1 + * @b: user data 2 + * + * Attaches an eval start callback @fn to @im. + * + * Eval start callbacks are called at the beginning of evaluation. They are a + * good + * place to get ready to give progress notification. + * They can be called + * many times. Every evalend call is guaranteed to have a matching evalstart, + * but not necessarily any eval calls. + * + * Eval callbacks are inherited. That is, any images which use your image + * as input will inherit your eval callbacks. As a result, if you add an + * eval callback to an image, you will be notified if any later image uses + * your image for computation. + * + * If a later image adds eval callbacks, then the inheritance is broken, + * and that image will recieve notification instead. + * + * See also: im_add_eval_callback(), im_add_evalend_callback(). + */ int -im_add_evalstart_callback( IMAGE *im, int (*fn)(), void *a, void *b ) +im_add_evalstart_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ) { return( add_callback( im, &im->evalstartfns, fn, a, b ) ); } +/** + * im_add_invalidate_callback: + * @im: image to attach callback to + * @fn: callback function + * @a: user data 1 + * @b: user data 2 + * + * Attaches an invalidate callback @fn to @im. + * + * Invalidate callbacks are triggered + * when VIPS invalidates the cache on an image. This is useful for + * removing images from other, higher-level caches. + * + * See also: im_invalidate(). + */ int -im_add_invalidate_callback( IMAGE *im, int (*fn)(), void *a, void *b ) +im_add_invalidate_callback( IMAGE *im, im_callback_fn fn, void *a, void *b ) { return( add_callback( im, &im->invalidatefns, fn, a, b ) ); } diff --git a/libvips/iofuncs/meta.c b/libvips/iofuncs/meta.c index fd308275..fc3b6f6f 100644 --- a/libvips/iofuncs/meta.c +++ b/libvips/iofuncs/meta.c @@ -86,7 +86,7 @@ * SECTION: meta * @short_description: get and set image metadata * @stability: Stable - * @see_also: header + * @see_also: header * @include: vips/vips.h * * You can attach arbitrary metadata to images. Metadata is copied as images