libvips

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.

[skip]

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

Return a new VipsOperation with the specified nickname. Useful for language bindings.

You'll need to set any arguments and build the operation before you can use it. See vips_call() for a higher-level way to make new operations.

[constructor]

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. Also called automatically on vips_shutdown().

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 .

Operators that have been tagged as invalid by the invalidate signal are removed from cache.

Operators with the VIPS_OPERATION_BLOCKED flag are never executed.

Operators with the VIPS_OPERATION_REVALIDATE flag are always executed and any old cache value is replaced.

Operators with the VIPS_OPERATION_NOCACHE flag are never cached.

[skip]

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

libvips only tracks memory it allocates, it can't track memory allocated by external libraries. If you use an operation like vips_magickload(), most of the memory it uses won't be included.

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

libvips only tracks file descriptors it allocates, it can't track ones allocated by external libraries. If you use an operation like vips_magickload(), most of the descriptors it uses won't be included.

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.

You can set the environment variable VIPS_TRACE to turn this option on, or use the command-line flag --vips-cache-trace.

See also: vips_cache_set_dump().

vips_concurrency_set ()

void
vips_concurrency_set (int concurrency);

Sets the number of worker threads that vips should use when running a VipsThreadPool.

The special value 0 means "default". In this case, the number of threads is set by the environment variable VIPS_CONCURRENCY, or if that is not set, the number of threads available on the host machine.

See also: vips_concurrency_get().

vips_concurrency_get ()

int
vips_concurrency_get (void);

Returns the number of worker threads that vips should use when running a VipsThreadPool.

vips gets this values from these sources in turn:

If vips_concurrency_set() has been called, this value is used. The special value 0 means "default". You can also use the command-line argument "--vips-concurrency" to set this value.

If vips_concurrency_set() has not been called and no command-line argument was used, vips uses the value of the environment variable VIPS_CONCURRENCY,

If VIPS_CONCURRENCY has not been set, vips finds the number of hardware threads that the host machine can run in parallel and uses that value.

The final value is clipped to the range 1 - 1024.

See also: vips_concurrency_get().

vips_operation_block_set ()

void
vips_operation_block_set (const char *name,
                          gboolean state);

Set the block state on all operations in the libvips class hierarchy at name and below.

For example:

1
2

vips_operation_block_set("VipsForeignLoad", TRUE);
vips_operation_block_set("VipsForeignLoadJpeg", FALSE);

Will block all load operations, except JPEG.

Use vips -l at the command-line to see the class hierarchy.

This call does nothing if the named operation is not found.

See also: vips_block_untrusted_set().

enum VipsOperationFlags

Flags we associate with an operation.

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

Every scan-line must be requested, you are not allowed to skip ahead, but as a special case, the very first request can be for a region not at the top of the image. In this case, the first part of the image will be read and discarded

Every scan-line must be requested, you are not allowed to skip ahead, but as a special case, the very first request can be for a region not at the top of the image. In this case, the first part of the image will be read and discarded

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.

VIPS_OPERATION_UNTRUSTED means the operation depends on external libraries which have not been hardened against attack. It should probably not be used on untrusted input. Use vips_block_untrusted_set() to block all untrusted operations.

VIPS_OPERATION_BLOCKED means the operation is prevented from executing. Use vips_operation_block_set() to enable and disable groups of operations.

VIPS_OPERATION_REVALIDATE force the operation to run, updating the cache with the new value. This is used by eg. VipsForeignLoad to implement the "revalidate" argument.

The “invalidate” signal

void
user_function (VipsOperation *vipsoperation,
               gpointer       user_data)

Flags: Run Last