VipsOperation and reference counting

After calling a VipsOperation you are responsible for unreffing any output objects. For example, consider:

1
2
3
4
5

VipsImage *im = ...;
VipsImage *t1; 

if (vips_invert (im, &t1, NULL)) 
  error ..

This will invert im and return a new VipsImage, t1 . As the caller of vips_invert(), you are responsible for t1 and must unref it when you no longer need it. If vips_invert() fails, no t1 is returned and you don't need to do anything.

If you don't need to use im for another operation, you can unref im immediately after the call. If im is needed to calculate t1 , vips_invert() will add a ref to im and automatically drop it when t1 is unreffed.

Consider running two operations, one after the other. You could write:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

VipsImage *im = ...;
VipsImage *t1, *t2;

if (vips_invert (im, &t1, NULL)) {
  g_object_unref (im);
  return -1;
}
g_object_unref (im);

if (vips_flip (t1, &t2, VIPS_DIRECTION_HORIZONTAL, NULL)) {
  g_object_unref (t1);
  return -1;
}
g_object_unref (t1);

This is correct, but rather long-winded. libvips provides a handy thing to make a vector of auto-freeing object references. You can write this as:

1
2
3
4
5
6
7

VipsObject *parent = ...;
VipsImage *im = ...;
VipsImage *t = (VipsImage **) vips_object_local_array (parent, 2);

if (vips_invert (im, &t[0], NULL) ||
  vips_flip (t[0], &t[1], VIPS_DIRECTION_HORIZONTAL, NULL))
  return -1;

where parent is some enclosing object which will be unreffed when this task is complete. vips_object_local_array() makes an array of VipsObject (or VipsImage, in this case) where when parent is freed, all non-NULL VipsObject in the array are also unreffed.

The VipsOperation cache

Because all VipsObject are immutable, they can be cached. The cache is very simple to use: instead of calling vips_object_build(), call vips_cache_operation_build(). This function calculates a hash from the operations's input arguments and looks it up in table of all recent operations. If there's a hit, the new operation is unreffed, the old operation reffed, and the old operation returned in place of the new one.

The cache size is controlled with vips_cache_set_max() and friends.

VipsOperationBuildFn ()

gboolean
(*VipsOperationBuildFn) (VipsObject *object);

vips_operation_get_flags ()

VipsOperationFlags
vips_operation_get_flags (VipsOperation *operation);

Returns the set of flags for this operation.

vips_operation_class_print_usage ()

void
vips_operation_class_print_usage (VipsOperationClass *operation_class);

Print a usage message for the operation to stdout.

vips_operation_invalidate ()

void
vips_operation_invalidate (VipsOperation *operation);

vips_operation_call_valist ()

int
vips_operation_call_valist (VipsOperation *operation,
                            va_list ap);

vips_operation_new ()

VipsOperation *
vips_operation_new (const char *name);

vips_call_required_optional ()

int
vips_call_required_optional (VipsOperation **operation,
                             va_list required,
                             va_list optional);

This is the main entry point for the C and C++ varargs APIs. operation is executed, supplying required and optional arguments.

Beware, this can change operation to point at an old, cached one.

vips_call ()

int
vips_call (const char *operation_name,
           ...);

vips_call() calls the named operation, passing in required arguments and then setting any optional ones from the remainder of the arguments as a set of name/value pairs.

For example, vips_embed() takes six required arguments, in , out , x , y , width , height , and has two optional arguments, extend and background . You can run it with vips_call() like this:

1
2
3
4
5
6
7

VipsImage *in = ...
VipsImage *out;

if( vips_call( "embed", in, &out, 10, 10, 100, 100,
    "extend", VIPS_EXTEND_COPY,
    NULL ) )
    ... error

Normally of course you'd just use the vips_embed() wrapper function and get type-safety for the required arguments.

See also: vips_call_split(), vips_call_options().

vips_call_split ()

int
vips_call_split (const char *operation_name,
                 va_list optional,
                 ...);

vips_call_split_option_string ()

int
vips_call_split_option_string (const char *operation_name,
                               const char *option_string,
                               va_list optional,
                               ...);

vips_call_options ()

void
vips_call_options (GOptionGroup *group,
                   VipsOperation *operation);

vips_call_argv ()

int
vips_call_argv (VipsOperation *operation,
                int argc,
                char **argv);

vips_cache_drop_all ()

void
vips_cache_drop_all (void);

Drop the whole operation cache, handy for leak tracking.

vips_cache_operation_buildp ()

int
vips_cache_operation_buildp (VipsOperation **operation);

Look up operation in the cache. If we get a hit, unref operation , ref the old one and return that through the argument pointer.

If we miss, build and add operation .

vips_cache_operation_build ()

VipsOperation *
vips_cache_operation_build (VipsOperation *operation);

A binding-friendly version of vips_cache_operation_buildp().

After calling this, operation has the same ref count as when it went in, and the result must be freed with vips_object_unref_outputs() and g_object_unref().

vips_cache_print ()

void
vips_cache_print (void);

Print the whole operation cache to stdout. Handy for debugging.

vips_cache_set_max ()

void
vips_cache_set_max (int max);

Set the maximum number of operations we keep in cache.

vips_cache_set_max_mem ()

void
vips_cache_set_max_mem (size_t max_mem);

Set the maximum amount of tracked memory we allow before we start dropping cached operations. See vips_tracked_get_mem().

See also: vips_tracked_get_mem().

vips_cache_get_max ()

int
vips_cache_get_max (void);

Get the maximum number of operations we keep in cache.

vips_cache_get_size ()

int
vips_cache_get_size (void);

Get the current number of operations in cache.

vips_cache_get_max_mem ()

size_t
vips_cache_get_max_mem (void);

Get the maximum amount of tracked memory we allow before we start dropping cached operations. See vips_tracked_get_mem().

See also: vips_tracked_get_mem().

vips_cache_get_max_files ()

int
vips_cache_get_max_files (void);

Get the maximum number of tracked files we allow before we start dropping cached operations. See vips_tracked_get_files().

See also: vips_tracked_get_files().

vips_cache_set_max_files ()

void
vips_cache_set_max_files (int max_files);

Set the maximum number of tracked files we allow before we start dropping cached operations. See vips_tracked_get_files().

See also: vips_tracked_get_files().

vips_cache_set_dump ()

void
vips_cache_set_dump (gboolean dump);

Handy for debugging. Print the operation cache to stdout just before exit.

See also: vips_cache_set_trace().

vips_cache_set_trace ()

void
vips_cache_set_trace (gboolean trace);

Handy for debugging. Print operation cache actions to stdout as we run.

See also: vips_cache_set_dump().

enum VipsOperationFlags

Flags we associate with an operation.

VIPS_OPERATION_SEQUENTIAL means that the operation works like vips_conv(): it can happily process images top-to-bottom with only small non-local references.

VIPS_OPERATION_SEQUENTIAL_UNBUFFERED means that the operation works like vips_copy(): it can happily process images top-to-bottom and makes no non-local references.

VIPS_OPERATION_NOCACHE means that the operation must not be cached by vips.

VIPS_OPERATION_DEPRECATED means this is an old operation kept in vips for compatibility only and should be hidden from users.

The “invalidate” signal

void
user_function (VipsOperation *vipsoperation,
               gpointer       user_data)

Flags: Run Last