VLFeat - Documentation > C API

# VLFeat.org

Documentation> C API

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

Functions
generic.c File Reference

Generic - Definition. More...

`#include "generic.h"`
`#include <assert.h>`
`#include <stdlib.h>`
`#include <stdio.h>`
`#include <stdarg.h>`
`#include <math.h>`
`#include <Windows.h>`
`#include <unistd.h>`

## Functions

VlState * | vl_get_state (void)
| Return VLFeat global state. More...
VlThreadState * | vl_get_thread_specific_state (void)
| Get VLFeat thread state. More...
static void | vl_lock_state (void)
| Lock VLFeat state. More...
static void | vl_unlock_state (void)
| Unlock VLFeat state. More...
static VlThreadState * | vl_thread_specific_state_new (void)
| Construct a new thread state object. More...
static void | vl_thread_specific_state_delete (VlThreadState *self)
| Delete a thread state structure. More...
char const * | vl_get_version_string ()
| Get VLFeat version string. More...
char * | vl_configuration_to_string_copy ()
| Get VLFeat configuration string. More...
static int | do_nothing_printf (char const *format,...)
| A printf that does not do anything. More...
vl_size | vl_get_num_cpus (void)
| Get the number of CPU cores of the host. More...
void | vl_set_simd_enabled (vl_bool x)
| Toggle usage of SIMD instructions. More...
vl_bool | vl_get_simd_enabled (void)
| Are SIMD instructons enabled? More...
vl_bool | vl_cpu_has_avx (void)
| Check for AVX instruction set. More...
vl_bool | vl_cpu_has_sse3 (void)
| Check for SSE3 instruction set. More...
vl_bool | vl_cpu_has_sse2 (void)
| Check for SSE2 instruction set. More...
vl_size | vl_get_thread_limit (void)
| Get the number of computational threads available to the application. More...
vl_size | vl_get_max_threads (void)
| Get the maximum number of computational threads used by VLFeat. More...
void | vl_set_num_threads (vl_size numThreads)
| Set the maximum number of threads used by VLFeat. More...
int | vl_set_last_error (int error, char const *errorMessage,...)
| Set last VLFeat error. More...
int | vl_get_last_error (void)
| Get the code of the last error. More...
char const * | vl_get_last_error_message (void)
| Get the last error message. More...
void | vl_set_alloc_func (void *(*malloc_func)(size_t), void *(*realloc_func)(void *, size_t), void *(*calloc_func)(size_t, size_t), void(*free_func)(void *))
| Set memory allocation functions. More...
void * | vl_malloc (size_t n)
| Allocate a memory block. More...
void * | vl_realloc (void *ptr, size_t n)
| Reallocate a memory block. More...
void * | vl_calloc (size_t n, size_t size)
| Free and clear a memory block. More...
void | vl_free (void *ptr)
| Free a memory block. More...
void | vl_set_printf_func (printf_func_t printf_func)
| Set the printf function. More...
printf_func_t | vl_get_printf_func (void)
| Get the printf function. More...
double | vl_get_cpu_time ()
| Get processor time. More...
void | vl_tic (void)
| Reset processor time reference The function resets VLFeat TIC/TOC time reference. There is one such reference per thread. More...
double | vl_toc (void)
| Get elapsed time since tic. More...
VlRand * | vl_get_rand (void)
| Get the default random number generator. More...
static void | vl_constructor (void)
| Initialize VLFeat state. More...
static void | vl_destructor ()
| Destruct VLFeat. More...

## Detailed Description

Author
  Andrea Vedaldi

## Function Documentation

static int do_nothing_printf | ( | char const * | format,
|  |  | ...
| ) |  |

static

void* vl_calloc | ( | size_t | n,
|  | size_t | size
| ) |  |

Parameters

  n | number of items to allocate.
  size | size in bytes of an item.

Returns
  pointer to the new block.

This function allocates and clears a memory block. The synopsis is the same as the POSIX `calloc` function.

char* vl_configuration_to_string_copy | ( | void |  | ) |

Returns
  a new configuration string.

The function returns a new string containing a human readable description of the library configuration.

static void vl_constructor | ( | void |  | ) |

static

vl_bool vl_cpu_has_avx | ( | void |  | ) |

Returns
  `true` if AVX is present.

vl_bool vl_cpu_has_sse2 | ( | void |  | ) |

Returns
  `true` if SSE2 is present.

vl_bool vl_cpu_has_sse3 | ( | void |  | ) |

Returns
  `true` if SSE3 is present.

static void vl_destructor | ( |  | ) |

static

void vl_free | ( | void * | ptr | ) |

Parameters

  ptr | pointer to the memory block.

This function frees a memory block allocated by vl_malloc, vl_calloc, or vl_realloc. The synopsis is the same as the POSIX `malloc` function.

double vl_get_cpu_time | ( | void |  | ) |

Returns
  processor time in seconds.

See also
  vl_tic, vl_toc

int vl_get_last_error | ( | void |  | ) |

Returns
  error code.

See also
  vl_get_last_error_message.

char const* vl_get_last_error_message | ( | void |  | ) |

Returns
  pointer to the error message.

See also
  vl_get_last_error.

vl_size vl_get_max_threads | ( | void |  | ) |

Returns
  number of threads.

This function returns the maximum number of thread used by VLFeat. VLFeat will try to use this number of computational threads and never exceed it.

This is similar to the OpenMP function `omp_get_max_threads()`; however, it reads a parameter private to VLFeat which is independent of the value used by the OpenMP library.

If VLFeat was compiled without OpenMP support, this function returns 1.

See also
  vl_set_num_threads(), Parallel computations

vl_size vl_get_num_cpus | ( | void |  | ) |

Returns
  number of CPU cores.

printf_func_t vl_get_printf_func | ( | void |  | ) |

Returns
  printf_func pointer to the `printf` implementation.

See also
  vl_set_printf_func.

VlRand* vl_get_rand | ( | void |  | ) |

Returns
  random number generator.

The function returns a pointer to the default random number generator. There is one such generator per thread.

vl_bool vl_get_simd_enabled | ( | void |  | ) |

Returns
  `true` if SIMD instructions are enabled.

VlState * vl_get_state | ( | void |  | ) |

inline

The function returns a pointer to VLFeat global state.

Returns
  pointer to the global state structure.

vl_size vl_get_thread_limit | ( | void |  | ) |

Returns
  number of threads.

This function wraps the OpenMP function `omp_get_thread_limit()`. If VLFeat was compiled without OpenMP support, this function returns 1. If VLFeat was compiled with OpenMP prior to version 3.0 (2008/05), it returns 0.

See also
  Parallel computations

VlThreadState * vl_get_thread_specific_state | ( | void |  | ) |

inline

Returns
  pointer to the thread state structure.

The function returns a pointer to VLFeat thread state.

char const* vl_get_version_string | ( | void |  | ) |

Returns
  the library version string.

static void vl_lock_state | ( | void |  | ) |

static

The function locks VLFeat global state mutex.

The mutex is recursive: locking multiple times from the same thread is a valid operations, but requires an equivalent number of calls to vl_unlock_state.

See also
  vl_unlock_state

void* vl_malloc | ( | size_t | n | ) |

Parameters

  n | size in bytes of the new block.

Returns
  pointer to the allocated block.

This function allocates a memory block of the specified size. The synopsis is the same as the POSIX `malloc` function.

void* vl_realloc | ( | void * | ptr,
|  | size_t | n
| ) |  |

Parameters

  ptr | pointer to a memory block previously allocated.
  n | size in bytes of the new block.

Returns
  pointer to the new block.

This function reallocates a memory block to change its size. The synopsis is the same as the POSIX `realloc` function.

void vl_set_alloc_func | ( | void *(*)(size_t) | malloc_func,
|  | void *(*)(void *, size_t) | realloc_func,
|  | void *(*)(size_t, size_t) | calloc_func,
|  | void(*)(void *) | free_func
| ) |  |

Parameters

  malloc_func | pointer to `malloc`.
  realloc_func | pointer to `realloc`.
  calloc_func | pointer to `calloc`.
  free_func | pointer to `free`.

int vl_set_last_error | ( | int | error,
|  | char const * | errorMessage,
|  |  | ...
| ) |  |

Parameters

  error | error code.
  errorMessage | error message format string.
  ... | format string arguments.

Returns
  error code.

The function sets the code and optionally the error message of the last encountered error. errorMessage is the message format. It uses the `printf` convention and is followed by the format arguments. The maximum length of the error message is given by VL_ERR_MSG_LEN (longer messages are truncated).

Passing `NULL` as errorMessage sets the error message to the empty string.

void vl_set_num_threads | ( | vl_size | numThreads | ) |

Parameters

  numThreads | number of threads to use.

This function sets the maximum number of computational threads that will be used by VLFeat. VLFeat may in practice use fewer threads (for example because numThreads is larger than the number of computational cores in the host, or because the number of threads exceeds the limit available to the application).

If `numThreads` is set to 0, then VLFeat sets the number of threads to the OpenMP current maximum, obtained by calling `omp_get_max_threads()`.

This function is similar to `omp_set_num_threads()` but changes a parameter internal to VLFeat rather than affecting OpenMP global state.

If VLFeat was compiled without, this function does nothing.

See also
  vl_get_max_threads(), Parallel computations

void vl_set_printf_func | ( | printf_func_t | printf_func | ) |

Parameters

  printf_func | pointer to a `printf` implementation. Set `print_func` to NULL to disable printf.

vl_set_simd_enabled | ( | vl_bool | x | ) |

Parameters

  x | `true` if SIMD instructions are used.

Notice that SIMD instructions are used only if the CPU model supports them. Note also that data alignment may restrict the use of such instructions.

See also
  vl_cpu_has_sse2(), vl_cpu_has_sse3(), etc.

static void vl_thread_specific_state_delete | ( | VlThreadState * | self | ) |

static

Parameters

  self | thread state object.

static VlThreadState * vl_thread_specific_state_new | ( | void |  | ) |

static

Returns
  new state structure.

void vl_tic | ( | void |  | ) |

See also
  vl_get_cpu_time, vl_toc.

double vl_toc | ( | void |  | ) |

Returns
  elapsed time in seconds.

The function returns the processor time elapsed since vl_tic was called last.

Remarks
  In multi-threaded applications, there is an independent timer for each execution thread.
  On UNIX, this function uses the `clock()` system call. On Windows, it uses the `QueryPerformanceCounter()` system call, which is more accurate than `clock()` on this platform.

static void vl_unlock_state | ( | void |  | ) |

static

The function unlocks VLFeat global state mutex.

See also
  vl_lock_state