memory

memory — memory utilities

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

#define             VIPS_FREEF                          (F,
                                                         S)
#define             VIPS_FREE                           (S)
#define             VIPS_SETSTR                         (S,
                                                         V)
#define             VIPS_NEW                            (OBJ,
                                                         T)
#define             VIPS_ARRAY                          (OBJ,
                                                         N,
                                                         T)
void *              vips_malloc                         (VipsObject *object,
                                                         size_t size);
char *              vips_strdup                         (VipsObject *object,
                                                         const char *str);
int                 vips_free                           (void *buf);
void                vips_tracked_free                   (void *s);
void *              vips_tracked_malloc                 (size_t size);
size_t              vips_tracked_get_mem                (void);
size_t              vips_tracked_get_mem_highwater      (void);
int                 vips_tracked_get_allocs             (void);
int                 vips_tracked_open                   (const char *pathname,
                                                         int flags,
                                                         ...);
int                 vips_tracked_close                  (int fd);
int                 vips_tracked_get_files              (void);

Description

These functions cover two main areas.

First, some simple utility functions over the underlying g_malloc()/g_free() functions. Memory allocated and freeded using these functions is interchangeable with any other glib library.

Second, a pair of functions, vips_tracked_malloc() and vips_tracked_free(), which are NOT compatible. If you g_free() memory that has been allocated with vips_tracked_malloc() you will see crashes.

The tracked functions are only suitable for large allocations internal to the library, for example pixel buffers. libvips watches the total amount of live tracked memory and uses this information to decide when to trim caches.

Details

VIPS_FREEF()

#define             VIPS_FREEF( F, S )


VIPS_FREE()

#define VIPS_FREE( S ) VIPS_FREEF( g_free, (S) );


VIPS_SETSTR()

#define             VIPS_SETSTR( S, V )


VIPS_NEW()

#define             VIPS_NEW( OBJ, T )

OBJ :

allocate memory local to OBJ, or NULL for no auto-free

T :

type of thing to allocate

Returns :

A pointer of type T *, or NULL on error.

VIPS_ARRAY()

#define             VIPS_ARRAY( OBJ, N, T )

OBJ :

allocate memory local to OBJ, or NULL for no auto-free

N :

number of T 's to allocate

T :

type of thing to allocate

Returns :

A pointer of type T *, or NULL on error.

vips_malloc ()

void *              vips_malloc                         (VipsObject *object,
                                                         size_t size);

g_malloc() local to object, that is, the memory will be automatically freed for you when the object is closed. If object is NULL, you need to free the memory explicitly with g_free().

This function cannot fail. See vips_tracked_malloc() if you are allocating large amounts of memory.

See also: vips_tracked_malloc().

object :

allocate memory local to this VipsObject, or NULL

size :

number of bytes to allocate

Returns :

a pointer to the allocated memory

vips_strdup ()

char *              vips_strdup                         (VipsObject *object,
                                                         const char *str);

g_strdup() a string. When object is freed, the string will be freed for you. If object is NULL, you need to free the memory explicitly with g_free().

This function cannot fail.

See also: vips_malloc().

object :

allocate memory local to this VipsObject, or NULL

str :

string to copy

Returns :

a pointer to the allocated memory

vips_free ()

int                 vips_free                           (void *buf);

Frees memory with g_free() and returns 0. Handy for callbacks.

See also: vips_malloc().

buf :

memory to free

vips_tracked_free ()

void                vips_tracked_free                   (void *s);

Only use it to free memory that was previously allocated with vips_tracked_malloc() with a NULL first argument.

See also: vips_tracked_malloc().

s :

memory to free

vips_tracked_malloc ()

void *              vips_tracked_malloc                 (size_t size);

Allocate an area of memory that will be tracked by vips_tracked_get_mem() and friends.

If allocation fails, vips_malloc() returns NULL and sets an error message.

You must only free the memory returned with vips_tracked_free().

See also: vips_tracked_free(), vips_malloc().

size :

number of bytes to allocate

Returns :

a pointer to the allocated memory, or NULL on error.

vips_tracked_get_mem ()

size_t              vips_tracked_get_mem                (void);

Returns the number of bytes currently allocated via vips_malloc() and friends. vips uses this figure to decide when to start dropping cache, see VipsOperation.

Returns :

the number of currently allocated bytes

vips_tracked_get_mem_highwater ()

size_t              vips_tracked_get_mem_highwater      (void);

Returns the largest number of bytes simultaneously allocated via vips_tracked_malloc(). Handy for estimating max memory requirements for a program.

Returns :

the largest number of currently allocated bytes

vips_tracked_get_allocs ()

int                 vips_tracked_get_allocs             (void);

Returns the number of active allocations.

Returns :

the number of active allocations

vips_tracked_open ()

int                 vips_tracked_open                   (const char *pathname,
                                                         int flags,
                                                         ...);

Exactly as open(2), but the number of files current open via vips_tracked_open() is available via vips_tracked_get_files(). This is used by the vips operation cache to drop cache when the number of files available is low.

You must only close the file descriptor with vips_tracked_close().

See also: vips_tracked_close(), vips_tracked_get_files().

pathname :

name of file to open

flags :

flags for open()

Returns :

a file descriptor, or -1 on error.

vips_tracked_close ()

int                 vips_tracked_close                  (int fd);

Exactly as close(2), but update the number of files currently open via vips_tracked_get_files(). This is used by the vips operation cache to drop cache when the number of files available is low.

You must only close file descriptors opened with vips_tracked_open().

See also: vips_tracked_open(), vips_tracked_get_files().

fd :

file to close()

Returns :

a file descriptor, or -1 on error.

vips_tracked_get_files ()

int                 vips_tracked_get_files              (void);

Returns the number of open files.

Returns :

the number of open files