373 lines
10 KiB
C
373 lines
10 KiB
C
/* Close and generate callbacks.
|
|
*
|
|
* 1/7/93 JC
|
|
* 20/7/93 JC
|
|
* - eval callbacks added
|
|
* 16/8/94 JC
|
|
* - evalend callbacks added
|
|
* 16/1/04 JC
|
|
* - now always calls all callbacks, even if some fail
|
|
* 2/7/08
|
|
* - added invalidate callbacks
|
|
* 26/11/08
|
|
* - don't set im_error() on callback failed, that's the user's job
|
|
*/
|
|
|
|
/*
|
|
|
|
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
|
|
|
|
*/
|
|
|
|
#ifdef HAVE_CONFIG_H
|
|
#include <config.h>
|
|
#endif /*HAVE_CONFIG_H*/
|
|
#include <vips/intl.h>
|
|
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <stdarg.h>
|
|
|
|
#include <vips/vips.h>
|
|
|
|
#ifdef WITH_DMALLOC
|
|
#include <dmalloc.h>
|
|
#endif /*WITH_DMALLOC*/
|
|
|
|
/**
|
|
* SECTION: callback
|
|
* @short_description: image callbacks
|
|
* @stability: Stable
|
|
* @see_also: <link linkend="libvips-image">image</link>
|
|
* @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 */
|
|
im_callback_fn fn; /* callback function */
|
|
void *a, *b; /* arguments to callback */
|
|
} VCallback;
|
|
|
|
/* Add a callback to an IMAGE. We can't use IM_NEW(), note! Freed eventually by
|
|
* im__close(), or by im_generate(), etc. for evalend callbacks.
|
|
*/
|
|
static int
|
|
add_callback( IMAGE *im, GSList **cblist, im_callback_fn fn, void *a, void *b )
|
|
{
|
|
VCallback *cbs;
|
|
|
|
if( !(cbs = IM_NEW( NULL, VCallback )) )
|
|
return( -1 );
|
|
|
|
cbs->fn = fn;
|
|
cbs->a = a;
|
|
cbs->b = b;
|
|
cbs->im = im;
|
|
*cblist = g_slist_prepend( *cblist, cbs );
|
|
|
|
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. 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().
|
|
*
|
|
* Returns: 0 on success, or -1 on error.
|
|
*/
|
|
int
|
|
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_postclose_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.
|
|
*
|
|
* Post-close callbacks are triggered exactly once, just before the memory
|
|
* associated with @im is released.
|
|
*
|
|
* Close callbacks are a good place to delete temporary files. You can close
|
|
* other images and there may even be circularity in your close lists.
|
|
*
|
|
* Returns: 0 on success, or -1 on error.
|
|
*/
|
|
int
|
|
im_add_postclose_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
|
|
{
|
|
return( add_callback( im, &im->postclosefns, 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.
|
|
*
|
|
* Returns: 0 on success, or -1 on error.
|
|
*/
|
|
int
|
|
im_add_preclose_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
|
|
{
|
|
return( add_callback( im, &im->preclosefns, fn, a, b ) );
|
|
}
|
|
|
|
/**
|
|
* im_add_written_callback:
|
|
* @im: image to attach callback to
|
|
* @fn: callback function
|
|
* @a: user data 1
|
|
* @b: user data 2
|
|
*
|
|
* Attaches a written callback @fn to @im.
|
|
*
|
|
* Written callbacks are triggered exactly once, just after @im has been
|
|
* written to.
|
|
*
|
|
* Written callbacks are a good place to do background writes to files. VIPS
|
|
* uses them to implement (for example) writing to im_open("poop.jpg","w")
|
|
* triggering a write to jpeg.
|
|
*
|
|
* Evalend callbacks happen after a real write loop, whereas written is
|
|
* triggered even for just attaching some callbacks to a "p" image.
|
|
*
|
|
* Returns: 0 on success, or -1 on error.
|
|
*/
|
|
int
|
|
im_add_written_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
|
|
{
|
|
return( add_callback( im, &im->writtenfns, fn, a, b ) );
|
|
}
|
|
|
|
/**
|
|
* 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().
|
|
*
|
|
* Returns: 0 on success, or -1 on error.
|
|
*/
|
|
int
|
|
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.
|
|
* im__handle_eval() looks up the IMAGE it should signal on.
|
|
*/
|
|
im->progress = im;
|
|
|
|
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().
|
|
*
|
|
* Returns: 0 on success, or -1 on error.
|
|
*/
|
|
int
|
|
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().
|
|
*
|
|
* Returns: 0 on success, or -1 on error.
|
|
*/
|
|
int
|
|
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().
|
|
*
|
|
* Returns: 0 on success, or -1 on error.
|
|
*/
|
|
int
|
|
im_add_invalidate_callback( IMAGE *im, im_callback_fn fn, void *a, void *b )
|
|
{
|
|
return( add_callback( im, &im->invalidatefns, fn, a, b ) );
|
|
}
|
|
|
|
/* Perform a user callback.
|
|
*/
|
|
static void *
|
|
call_callback( VCallback *cbs, int *result )
|
|
{
|
|
int res;
|
|
|
|
if( (res = cbs->fn( cbs->a, cbs->b )) ) {
|
|
/* We don't set im_error() here, that's the callback's
|
|
* responsibility.
|
|
*/
|
|
*result = res;
|
|
|
|
#ifdef DEBUG_IO
|
|
printf( "im__trigger_callbacks: user callback "
|
|
"failed for %s\n", cbs->im->filename );
|
|
#endif /*DEBUG_IO*/
|
|
}
|
|
|
|
return( NULL );
|
|
}
|
|
|
|
/* Perform a list of user callbacks.
|
|
*/
|
|
int
|
|
im__trigger_callbacks( GSList *cblist )
|
|
{
|
|
int result;
|
|
|
|
#ifdef DEBUG_IO
|
|
printf( "im__trigger_callbacks: calling %d user callbacks ..\n",
|
|
g_slist_length( cblist ) );
|
|
#endif /*DEBUG_IO*/
|
|
|
|
result = 0;
|
|
(void) im_slist_map2( cblist,
|
|
(VSListMap2Fn) call_callback, &result, NULL );
|
|
|
|
return( result );
|
|
}
|