From 19c9cccbfc7f15dd8298a6aaec3c276204854802 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Fri, 9 Nov 2007 14:26:41 +0000 Subject: [PATCH] stuff --- TODO | 6 --- doc/src/iosys.tex | 16 +++---- doc/src/pio.tex | 50 ++++++++------------ man/Makefile.am | 2 + man/im_add_evalstart_callback.3 | 1 + man/im_add_preclose_callback.3 | 1 + man/im_malloc.3 | 83 +++++++++++++++------------------ 7 files changed, 69 insertions(+), 90 deletions(-) create mode 100644 man/im_add_evalstart_callback.3 create mode 100644 man/im_add_preclose_callback.3 diff --git a/TODO b/TODO index 87d367ae..ba4ba03c 100644 --- a/TODO +++ b/TODO @@ -16,12 +16,6 @@ is there a problem -- update docs, add pages for new cbs - - part of im_malloc.3 - - update nip2 for the new system ... seems to just be imageinfo_progress_add() - - test ppm writer - missing libstdc++ in link? what if we configure with no openexr? diff --git a/doc/src/iosys.tex b/doc/src/iosys.tex index 40b88e37..aeee2d9a 100644 --- a/doc/src/iosys.tex +++ b/doc/src/iosys.tex @@ -120,7 +120,7 @@ typedef struct { /* Derived fields that may be read by the user. */ char *filename; /* File name */ - struct time_info *time;/* Timing for eval callback */ + im_time_t *time; /* Timing for eval callback */ int kill; /* Set to non-zero to block eval */ ... and lots of other private fields used by VIPS for @@ -592,13 +592,12 @@ descriptor. The base memory allocation function is \verb+im_malloc()+. It has type: \begin{verbatim} -void *im_malloc( IMAGE *im, - size_t size ) +void *im_malloc( IMAGE *, size_t ) \end{verbatim} It operates exactly as the standard \verb+malloc()+ C library function, -except that the area of memory it allocates is local to image descriptor -\verb+im+. If \verb+im_malloc()+ is unable to allocate memory, it returns +except that the area of memory it allocates is local to an image. +If \verb+im_malloc()+ is unable to allocate memory, it returns \verb+NULL+. If you pass \verb+NULL+ instead of a valid image descriptor, then \verb+im_malloc()+ allocates memory globally and you must free it yourself at some stage. @@ -606,7 +605,7 @@ yourself at some stage. To free memory explicitly, use \verb+im_free()+: \begin{verbatim} -int im_free( void *mem ) +int im_free( void * ) \end{verbatim} \noindent @@ -618,7 +617,7 @@ a new object. You give it a descriptor and a type, and it returns a pointer to enough space to hold an object of that type. It has type: \begin{verbatim} -type-name *IM_NEW( IMAGE *im, type-name ) +type-name *IM_NEW( IMAGE *, type-name ) \end{verbatim} The second macro, \verb+IM_ARRAY()+, is very similar, but allocates @@ -626,8 +625,7 @@ space for an array of objects. Note that, unlike the usual \verb+calloc()+ C library function, it does not initialise the array to zero. It has type: \begin{verbatim} -type-name *IM_ARRAY( IMAGE *im, - int n, type-name ) +type-name *IM_ARRAY( IMAGE *, int, type-name ) \end{verbatim} Finally, \verb+IM_NUMBER()+ returns the number of elements in an array of diff --git a/doc/src/pio.tex b/doc/src/pio.tex index c951c50d..4db68553 100644 --- a/doc/src/pio.tex +++ b/doc/src/pio.tex @@ -797,8 +797,7 @@ 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. This release -of VIPS supports three callbacks: +you provide that VIPS will call when certain events occur. \subsubsection{Close callbacks} @@ -806,44 +805,35 @@ These callbacks are invoked just before an image is closed. They are useful for freeing objects which are associated with the image. All callbacks are triggered in the reverse order to the order in which they were attached. This is sometimes important when freeing objects which contain pointers to -other objects. +other objects. Close callbacks are guaranteed to be called, and to be called +exactly once. Use \verb+im_add_close_callback()+ to add a close callback: \begin{verbatim} -int -im_add_close_callback( IMAGE *im, - int (*callback)(), - void *a, void *b ) +typedef int (*im_callback)( void *, void * ) +int im_add_close_callback( IMAGE *, + im_callback_fn, + void *, void * ) \end{verbatim} -\noindent -where \verb+callback()+ is a function supplied by you which has type: - -\begin{verbatim} -int callback( void *a, void *b ) -\end{verbatim} - -\noindent -and which returns 0 on success, and -1 on error, setting -\verb+im_error()+. As with \verb+im_generate()+, the values \verb+a+ -and \verb+b+ are carried around for you by VIPS, and may be used as your +As with \verb+im_generate()+, the two \verb+void *+ pointers +are carried around for you by VIPS and may be used as your function sees fit. +\subsubsection{Preclose callbacks} + +Preclose callbacks are called before any shutdown has occured. Everything is +still alive and your callback can do anything to the image. Preclose callbacks +are guaranteed to be called, and to be called exactly once. See the manual +page for \verb+im_add_preclose_callback()+ for full details. + \subsubsection{Eval callbacks} -These are callbacks which are invoked by VIPS during evaluation. They -are called each time a region is filled with data (for PIO functions), or -each time \verb+im_writeline()+ is called (for WIO functions). The callback -has access to a large struct containing information about the progress of -evaluation, useful for user-interfaces built on top of VIPS. See the manual -page for \verb+im_add_eval_callback()+ for full details. - -\subsubsection{Evalend callbacks} - -These are triggered after completion of evaluation of an image, just after all -stop functions have been called. Evalend callbacks are useful for summarising -the results of a computation, see the example in the section below. +These are callbacks which are invoked periodically by VIPS during evaluation. +The callback has access to a struct containing information about the progress +of evaluation, useful for user-interfaces built on top of VIPS. See the +manual page for \verb+im_add_eval_callback()+ for full details. \subsection{Memory allocation revisited} diff --git a/man/Makefile.am b/man/Makefile.am index 0cbdb961..4a3696bc 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -20,7 +20,9 @@ man_MANS = \ im_abs.3 \ im_acostra.3 \ im_add.3 \ + im_add_preclose_callback.3 \ im_add_close_callback.3 \ + im_add_evalstart_callback.3 \ im_add_eval_callback.3 \ im_add_evalend_callback.3 \ im_addgnoise.3 \ diff --git a/man/im_add_evalstart_callback.3 b/man/im_add_evalstart_callback.3 new file mode 100644 index 00000000..0be9c41f --- /dev/null +++ b/man/im_add_evalstart_callback.3 @@ -0,0 +1 @@ +.so man3/im_malloc.3 diff --git a/man/im_add_preclose_callback.3 b/man/im_add_preclose_callback.3 new file mode 100644 index 00000000..0be9c41f --- /dev/null +++ b/man/im_add_preclose_callback.3 @@ -0,0 +1 @@ +.so man3/im_malloc.3 diff --git a/man/im_malloc.3 b/man/im_malloc.3 index bb2f0cd5..2f3fb265 100644 --- a/man/im_malloc.3 +++ b/man/im_malloc.3 @@ -1,51 +1,25 @@ .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 \- add image callbacks +im_add_evalend_callback, im_add_evalstart_callback, im_add_preclose_callback \- add image callbacks .SH SYNOPSIS .B #include -int im_add_close_callback( im, fn, a, b ) -.br -IMAGE *im; -.br -int (*fn)(); -.br -void *a, *b; +typedef int (*im_callback_fn)( void *, void * ); -int im_add_evalend_callback( im, fn, a, b ) -.br -IMAGE *im; -.br -int (*fn)(); -.br -void *a, *b; +int im_add_close_callback( IMAGE *, im_callback_fn, void *, void * ); -where +int im_add_preclose_callback( IMAGE *, im_callback_fn, void *, void * ); -int fn( a, b ) -.br -void *a, *b; +int im_add_evalstart_callback( IMAGE *, im_callback_fn, void *, void * ); -char *im_malloc( IMAGE *im, int size ); +int im_add_eval_callback( IMAGE *, im_callback_fn, void *, void * ); -int im_free( void *s ); +int im_add_evalend_callback( IMAGE *, im_callback_fn, void *, void * ); -.B #include +void *im_malloc( IMAGE *, size_t ); -int im_add_eval_callback( im, fn, a, b ) -.br -IMAGE *im; -.br -int (*fn)(); -.br -void *a, *b; - -where - -int fn( a, b ) -.br -void *a, *b; +int im_free( void * ); .SH DESCRIPTION These functions attach callbacks to images. Callbacks are functions, with @@ -62,7 +36,8 @@ is closed by The callback is expected to return 0 for success and non-zero for failure. If the function fails, then the whole .B im_close(3) -fails. +fails. Close callbacks are guaranteed to be called exactly once, so they are a +good place to release resources. This function is used by VIPS to implement .B im_malloc(3). @@ -93,16 +68,27 @@ may even be circularity in your .B im_close(3) lists. -.B im_add_evalend_callback(3) -adds a callback which will be triggered when VIPS -has finished writing to the descriptor. If you want to output some diagnostics -from your function (an overflow count, for example), this is the callback to -use. +.B im_add_preclose_callback(3) +adds a callback which will be triggered when the image is closed, but before +any closing has started. Everything is still alive and you can do anything +with the image. Preclose callbacks are guaranteed to be called exactly once. + +.B im_add_evalstart_callback(3) +adds a callback which will be triggered just before image evaluation starts. +It can be called many times. It's a good place to initalize data structures. +Don't allocate resources here. + +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. .B im_add_eval_callback(3) adds a callback which will be triggered repeatedly as -the image is written to. This works for both PIO and WIO images, -although it is rather more successful with PIO image output. +the image is evaluated. When the callback is triggered, the time field of the descriptor will point to a @@ -111,12 +97,13 @@ structure, see vips.h typedef struct { IMAGE *im; /* Image we are part of */ - GTimer *start; /* Start time */ + time_t unused; /* For compatibility */ int run; /* Time we have been running (secs) */ int eta; /* Estimated seconds of computation left */ gint64 tpels; /* Number of pels we expect to calculate */ gint64 npels; /* Number of pels calculated so far */ int percent; /* Percent complete */ + GTimer *start; /* Start time */ } im_time_t; These fields are not exact! They should only be used to give approximate @@ -140,9 +127,15 @@ be used to provide a `cancel' feature in your user-interface. if( im_add_eval_callback( out, eval_cb, out, NULL ) ) return( -1 ); - ... now as we write to out, we will get %complete + ... now as out is evaluated, we will get %complete ... messages on stdout. +.B im_add_evalend_callback(3) +adds a callback which will be triggered when VIPS +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. + .SH RETURN VALUE All functions return 0 on success and non-zero on error. .SH SEE ALSO