memory

memory — memory utilities

Stability Level

Stable, unless otherwise indicated

Functions

#define VIPS_FREEF()
#define VIPS_FREE()
#define VIPS_SETSTR()
#define VIPS_NEW()
#define VIPS_ARRAY()
void * vips_malloc ()
char * vips_strdup ()
int vips_free ()
void vips_tracked_free ()
void * vips_tracked_malloc ()
size_t vips_tracked_get_mem ()
size_t vips_tracked_get_mem_highwater ()
int vips_tracked_get_allocs ()
int vips_tracked_open ()
int vips_tracked_close ()
int vips_tracked_get_files ()

Includes

#include <vips/vips.h>

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.

Functions

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 )

Allocate memory for a thing of type T . The memory is not cleared.

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

See also: vips_malloc().

Parameters

OBJ

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

 

T

type of thing to allocate

 

Returns

A pointer of type T *.


VIPS_ARRAY()

#define             VIPS_ARRAY( OBJ, N, T )

Allocate memory for an array of objects of type T . The memory is not cleared.

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

See also: vips_malloc().

Parameters

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 *.


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

Parameters

object

allocate memory local to this VipsObject, or NULL.

[nullable]

size

number of bytes to allocate

 

Returns

a pointer to the allocated memory.

[transfer full]


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 yourself with g_free().

This function cannot fail.

See also: vips_malloc().

Parameters

object

allocate memory local to this VipsObject, or NULL.

[nullable]

str

string to copy

 

Returns

a pointer to the allocated memory.

[transfer full]


vips_free ()

int
vips_free (void *buf);

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

See also: vips_malloc().

Parameters

buf

memory to free

 

Returns

0


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

Parameters

s

memory to free.

[transfer full]

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

Parameters

size

number of bytes to allocate

 

Returns

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

[transfer full]


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

pathname should be utf8.

See also: vips_tracked_close(), vips_tracked_get_files().

Parameters

pathname

name of file to open

 

flags

flags for open()

 

...

open mode

 

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

Parameters

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

Types and Values