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 it as 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.

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(), instead 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 *Param1);

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 ()

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