| VIPS Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | ||||
#include <vips/vips.h> VipsThreadState * (*VipsThreadStartFn) (VipsImage *im,void *a); VipsThreadState; VipsThreadStateClass; int (*VipsThreadpoolAllocateFn) (VipsThreadState *state,void *a,gboolean *stop); int (*VipsThreadpoolProgressFn) (void *a); int (*VipsThreadpoolWorkFn) (VipsThreadState *state,void *a); void vips__print_renders (void); int vips_concurrency_get (void); void vips_concurrency_set (int concurrency); void vips_get_tile_size (VipsImage *im,int *tile_width,int *tile_height,int *nlines); VipsThreadState * vips_thread_state_new (VipsImage *im,void *a); void * vips_thread_state_set (VipsObject *object,void *a,void *b); int vips_threadpool_run (VipsImage *im,VipsThreadStartFn start,VipsThreadpoolAllocateFn allocate,VipsThreadpoolWorkFn work,VipsThreadpoolProgressFn progress,void *a);
vips_threadpool_run() loops a set of threads over an image. Threads take it
in turns to allocate units of work (a unit might be a tile in an image),
then run in parallel to process those units. An optional progress function
can be used to give feedback.
typedef struct {
/* Image we run on.
*/
VipsImage *im;
/* This region is created and destroyed by the threadpool for the
* use of the worker.
*/
VipsRegion *reg;
/* Neither used nor set, do what you like with them.
*/
VipsRect pos;
int x, y;
/* Set in work to get the allocate to signal stop.
*/
gboolean stop;
/* The client data passed to the enclosing vips_threadpool_run().
*/
void *a;
} VipsThreadState;
These per-thread values are carried around for your use by
vips_threadpool_run(). They are private to each thread, so they are a
useful place
for VipsThreadpoolAllocate and VipsThreadpoolWork to communicate.
reg is created for you at the start of processing and freed at the end,
but you can do what you like with it.
VipsImage * |
the VipsImage being operated upon |
VipsRegion * |
a REGION |
VipsRect |
a Rect |
| an int | |
| an int | |
| client data |
int (*VipsThreadpoolAllocateFn) (VipsThreadState *state,void *a,gboolean *stop);
This function is called to allocate a new work unit for the thread. It is always single-threaded, so it can modify per-pool state (such as a counter).
a, b, c are the values supplied to the call to
vips_threadpool_run().
It should set stop to TRUE to indicate that no work could be allocated
because the job is done.
See also: vips_threadpool_run().
|
per-thread state |
|
client data |
|
client data |
|
client data |
|
set this to signal end of computation |
Returns : |
0 on success, or -1 on error |
int (*VipsThreadpoolProgressFn) (void *a);
This function is called by the main thread once for every work unit processed. It can be used to give the user progress feedback.
See also: vips_threadpool_run().
|
client data |
|
client data |
|
client data |
Returns : |
0 on success, or -1 on error |
int (*VipsThreadpoolWorkFn) (VipsThreadState *state,void *a);
This function is called to process a work unit. Many copies of this can run at once, so it should not write to the per-pool state. It can write to per-thread state.
a, b, c are the values supplied to the call to
vips_threadpool_run().
See also: vips_threadpool_run().
|
per-thread state |
|
client data |
|
client data |
|
client data |
Returns : |
0 on success, or -1 on error |
void vips_get_tile_size (VipsImage *im,int *tile_width,int *tile_height,int *nlines);
Pick a tile size and a buffer height for this image and the current
value of vips_concurrency_get(). The buffer height
will always be a multiple of tile_height.
|
image to guess for |
|
return selected tile width |
|
return selected tile height |
|
return buffer height in scanlines |
int vips_threadpool_run (VipsImage *im,VipsThreadStartFn start,VipsThreadpoolAllocateFn allocate,VipsThreadpoolWorkFn work,VipsThreadpoolProgressFn progress,void *a);
This function runs a set of threads over an image. Each thread first calls
start to create new per-thread state, then runs
allocate to set up a new work unit (perhaps the next tile in an image, for
example), then work to process that work unit. After each unit is
processed, progress is called, so that the operation can give
progress feedback. progress may be NULL.
Each thread has private state that the allocate and work functions can
use to communicate. This state is created by each worker as it starts using
start. Use the state destructor to clean up.
allocate and start are always single-threaded (so they can write to the
per-pool state), whereas work can be executed concurrently. progress is
always called by
the main thread (ie. the thread which called vips_threadpool_run()).
See also: vips_concurrency_set().
|
image to loop over |
|
allocate per-thread state |
|
allocate a work unit |
|
process a work unit |
|
give progress feedback about a work unit, or NULL
|
|
client data |
Returns : |
0 on success, or -1 on error. |