## memory memory — memory utilities |

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | VIPS_FREEF()
#define | VIPS_FREE()
#define | VIPS_SETSTR()
#define | VIPS_MALLOC()
#define | VIPS_NEW()
#define | VIPS_ARRAY()
void * | vips_malloc ()
char * | vips_strdup ()
void | vips_tracked_free ()
void | vips_tracked_aligned_free ()
void * | vips_tracked_malloc ()
void * | vips_tracked_aligned_alloc ()
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_MALLOC()

    #define             VIPS_MALLOC(OBJ, S)

### 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_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_aligned_free ()

    void
    vips_tracked_aligned_free (void *s);

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

See also: `vips_tracked_aligned_alloc()`.

#### 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_tracked_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_aligned_alloc ()

    void *
    vips_tracked_aligned_alloc (size_t size,
                                size_t align);

Allocate an area of memory aligned on a boundary specified by `align` that will be tracked by `vips_tracked_get_mem()` and friends.

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

You must only free the memory returned with `vips_tracked_aligned_free()`.

See also: `vips_tracked_malloc()`, `vips_tracked_aligned_free()`, `vips_malloc()`.

#### Parameters

size | number of bytes to allocate |
align | specifies the alignment |

#### 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,
                       int mode);

Exactly as open(2), but the number of files currently 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()` |
mode | 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