generic.h File Reference

Generic (General support functionalities) More...

#include "host.h"
#include "random.h"
#include <stdlib.h>
#include <stddef.h>
#include <time.h>
#include <assert.h>

Macros
#define	VL_VERSION_STRING   "0.9.21"
	Library version string.
#define	VL_ERR_MSG_LEN   1024
	Maximum length (in characters) of an error message.
Common operations
#define	VL_MIN(x, y)   (((x)<(y))?(x):(y))
	Compute the minimum between two values. More...
#define	VL_MAX(x, y)   (((x)>(y))?(x):(y))
	Compute the maximum between two values. More...
#define	VL_SHIFT_LEFT(x, n)   (((n)>=0)?((x)<<(n)):((x)>>-(n)))
	Signed left shift operation. More...

Functions
char const *	vl_get_version_string (void)
	Get VLFeat version string. More...
char *	vl_configuration_to_string_copy (void)
	Get VLFeat configuration string. 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_num_cpus (void)
	Get the number of CPU cores of the host. More...
VlRand *	vl_get_rand (void)
	Get the default random number generator. More...
Multi-thread computations
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 n)
	Set the maximum number of threads used by VLFeat. More...
vl_size	vl_get_thread_limit (void)
	Get the number of computational threads available to the application. More...
Memory allocation
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_memalign (size_t n, size_t size)
void	vl_free (void *ptr)
	Free a memory block. More...
Measuring time
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...
double	vl_get_cpu_time (void)
	Get processor time. More...

Type identifiers for atomic data types
#define	VL_TYPE_FLOAT   1
#define	VL_TYPE_DOUBLE   2
#define	VL_TYPE_INT8   3
#define	VL_TYPE_UINT8   4
#define	VL_TYPE_INT16   5
#define	VL_TYPE_UINT16   6
#define	VL_TYPE_INT32   7
#define	VL_TYPE_UINT32   8
#define	VL_TYPE_INT64   9
#define	VL_TYPE_UINT64   10
typedef vl_uint32	vl_type
char const *	vl_get_type_name (vl_type type)
	Get the name of a data type. More...
vl_size	vl_get_type_size (vl_type type)
	Get data type size. More...

Error handling
#define	VL_ERR_OK   0
#define	VL_ERR_OVERFLOW   1
#define	VL_ERR_ALLOC   2
#define	VL_ERR_BAD_ARG   3
#define	VL_ERR_IO   4
#define	VL_ERR_EOF   5
#define	VL_ERR_NO_MORE   5
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...
int	vl_set_last_error (int error, char const *errorMessage,...)
	Set last VLFeat error. More...

Logging
#define	VL_PRINTF   (*vl_get_printf_func())
	Call user-customizable printf function. More...
#define	VL_PRINT   (*vl_get_printf_func())
	Same as VL_PRINTF (legacy code)
typedef int(*	printf_func_t) (char const *format,...)
	Customizable printf function pointer type.
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...

Detailed Description

Author

Andrea Vedaldi

Macro Definition Documentation

VL_ERR_ALLOC

#define VL_ERR_ALLOC   2

Resource allocation error

VL_ERR_BAD_ARG

#define VL_ERR_BAD_ARG   3

Bad argument or illegal data error

VL_ERR_EOF

#define VL_ERR_EOF   5

End-of-file or end-of-sequence error

VL_ERR_IO

#define VL_ERR_IO   4

Input/output error

VL_ERR_NO_MORE

#define VL_ERR_NO_MORE   5

End-of-sequence

Deprecated:

VL_ERR_OK

#define VL_ERR_OK   0

No error

VL_ERR_OVERFLOW

#define VL_ERR_OVERFLOW   1

Buffer overflow error

VL_MAX

#define VL_MAX	(		x,
			y
	)		(((x)>(y))?(x):(y))

Parameters

x	value.
y	value.

Returns

the maximum of x and y.

VL_MIN

#define VL_MIN	(		x,
			y
	)		(((x)<(y))?(x):(y))

Parameters

x	value
y	value

Returns

the minimum of x and y.

VL_PRINTF

#define VL_PRINTF   (*vl_get_printf_func())

The function calls the user customizable printf.

VL_SHIFT_LEFT

#define VL_SHIFT_LEFT	(		x,
			n
	)		(((n)>=0)?((x)<<(n)):((x)>>-(n)))

Parameters

x	value.
n	number of shift positions.

Returns

x << n . The macro is equivalent to the builtin << operator, but it supports negative shifts too.

VL_TYPE_DOUBLE

#define VL_TYPE_DOUBLE   2

double type

VL_TYPE_FLOAT

#define VL_TYPE_FLOAT   1

float type

VL_TYPE_INT16

#define VL_TYPE_INT16   5

vl_int16 type

VL_TYPE_INT32

#define VL_TYPE_INT32   7

vl_int32 type

VL_TYPE_INT64

#define VL_TYPE_INT64   9

vl_int64 type

VL_TYPE_INT8

#define VL_TYPE_INT8   3

vl_int8 type

VL_TYPE_UINT16

#define VL_TYPE_UINT16   6

vl_uint16 type

VL_TYPE_UINT32

#define VL_TYPE_UINT32   8

vl_uint32 type

VL_TYPE_UINT64

#define VL_TYPE_UINT64   10

vl_uint64 type

VL_TYPE_UINT8

#define VL_TYPE_UINT8   4

vl_uint8 type

Function Documentation

vl_calloc()

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.

vl_configuration_to_string_copy()

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.

vl_cpu_has_avx()

vl_bool vl_cpu_has_avx

(

void

)

Returns

true if AVX is present.

vl_cpu_has_sse2()

vl_bool vl_cpu_has_sse2

(

void

)

Returns

true if SSE2 is present.

vl_cpu_has_sse3()

vl_bool vl_cpu_has_sse3

(

void

)

Returns

true if SSE3 is present.

vl_free()

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.

vl_get_cpu_time()

double vl_get_cpu_time

(

void

)

Returns

processor time in seconds.

See also

vl_tic, vl_toc

vl_get_last_error()

int vl_get_last_error

(

void

)

Returns

error code.

See also

vl_get_last_error_message.

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

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

vl_size vl_get_num_cpus

(

void

)

Returns

number of CPU cores.

vl_get_printf_func()

printf_func_t vl_get_printf_func

(

void

)

Returns

printf_func pointer to the printf implementation.

See also

vl_set_printf_func.

vl_get_rand()

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

vl_bool vl_get_simd_enabled

(

void

)

Returns

true if SIMD instructions are enabled.

vl_get_thread_limit()

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

vl_get_type_name()

char const* vl_get_type_name ( vl_type  type )

inline

Parameters

type	data type.

Returns

data name of the data type.

type is one of VL_TYPE_FLOAT, VL_TYPE_DOUBLE, VL_TYPE_INT8, VL_TYPE_INT16, VL_TYPE_INT32, VL_TYPE_INT64, VL_TYPE_UINT8, VL_TYPE_UINT16, VL_TYPE_UINT32, VL_TYPE_UINT64.

vl_get_type_size()

vl_size vl_get_type_size ( vl_type  type )

inline

Parameters

type	data type.

Returns

size (in byte)

type is one of VL_TYPE_FLOAT, VL_TYPE_DOUBLE, VL_TYPE_INT8, VL_TYPE_INT16, VL_TYPE_INT32, VL_TYPE_INT64, VL_TYPE_UINT8, VL_TYPE_UINT16, VL_TYPE_UINT32, VL_TYPE_UINT64.

vl_get_version_string()

char const* vl_get_version_string

(

void

)

Returns

the library version string.

vl_malloc()

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.

vl_realloc()

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.

vl_set_alloc_func()

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.

vl_set_last_error()

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.

vl_set_num_threads()

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

vl_set_printf_func()

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

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

vl_tic()

void vl_tic

(

void

)

See also

vl_get_cpu_time, vl_toc.

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.