C API

generic.h File Reference


Detailed Description

This module provides the following functionalities:

C preprocessor

VLFeat provides a few C preprocessor macros of general utility. These include stringification (VL_STRINGIFY, VL_XSTRINGIFY) and concatenation (VL_CAT, VL_XCAT) of symbols.

Error handling

Some VLFeat functions signal errors as the standard C library. Such functions return 0 when they succeed and -1 when they fail, and set the global variable vl_err_no with a code identifying the error occurred. This variable is never set on success and should be examined right after an error had occurred.

Heap allocation

VLFeat uses the vl_malloc(), vl_realloc(), vl_calloc() and vl_free() functions to allocate the heap. Normally these functions are mapped to the underlying standard C library implementations. However vl_set_alloc_func() can be used to map them to other implementations. For instance, in MATALB MEX files these functions are mapped to the MATLAB equivalent which has a garbage collection mechanism to cope with interruptions during execution.

Logging

VLFeat uses the macros VL_PRINT and VL_PRINTF to print progress or debug informations. These functions are normally mapped to the printf function of the underlying standard C library. However vl_set_printf_func() can be used to map it to a different implementation. For instance, in MATLAB MEX files this function is mapped to mexPrintf. Setting the function to NULL disables logging.

Measruing time

VLFeat provides vl_tic() and vl_toc() as an easy way of measuring elapsed time.

Author:
Andrea Vedaldi

Definition in file generic.h.

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

Go to the source code of this file.


Logging

#define VL_PRINTF   (*vl_printf_func)
 Call user-customizable printf function.
#define VL_PRINT   (*vl_printf_func)
 Same as VL_PRINTF (legacy code).
typedef int(* printf_func_t )(char const *format,...)
 Customizable printf function pointer type.
VL_EXPORT void vl_set_printf_func (printf_func_t printf_func)
 Set printf function.

Error handling

#define VL_ERR_MSG_LEN   1024
 The maximum length of an error description.
#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
VL_EXPORT int vl_err_no
 The number of the last error.
VL_EXPORT char vl_err_msg [VL_ERR_MSG_LEN+1]
 The description of the last error.

Defines

#define VL_VERSION_STRING   "0.9.4"
 Library version string.
#define VL_YESNO(x)   ((x)?"yes":"no")
 Convert a boolean to "yes" or "no" strings.
C preprocssor
#define VL_STRINGIFY(x)   # x
 Convert the argument to a string.
#define VL_XSTRINGIFY(x)   VL_STRINGIFY(x)
 Expand and then convert the argument to a string.
#define VL_CAT(x, y)   x ## y
 Concatenate the arguments into a lexical unit.
#define VL_XCAT(x, y)   VL_CAT(x,y)
 Expand and then concatenate the arguments into a lexical unit.
Common operations
#define VL_MIN(x, y)   (((x)<(y))?(x):(y))
 Min operation.
#define VL_MAX(x, y)   (((x)>(y))?(x):(y))
 Max operation.
#define VL_SHIFT_LEFT(x, n)   (((n)>=0)?((x)<<(n)):((x)>>-(n)))
 Signed left shift operation.

Functions

VL_EXPORT char const * vl_get_version_string ()
 Get version string.
VL_EXPORT void vl_print_info ()
 Print information about the library.
Heap allocation
VL_EXPORT 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.
VL_INLINE void * vl_malloc (size_t n)
 Call customizable malloc function.
VL_INLINE void * vl_realloc (void *ptr, size_t n)
 Call customizable resize function.
VL_INLINE void * vl_calloc (size_t n, size_t size)
 Call customizable calloc function.
VL_INLINE void vl_free (void *ptr)
 Call customizable free function.
Measuring time
VL_EXPORT void vl_tic ()
 Set time reference.
VL_EXPORT double vl_toc ()
 Get time since reference.

Variables

VL_EXPORT int(* vl_printf_func )(char const *format,...)
 Customizable printf function pointer.
VL_EXPORT void *(* vl_malloc_func )(size_t)
 Customizable malloc function pointer.
VL_EXPORT void *(* vl_realloc_func )(void *, size_t)
 Customizable realloc function pointer.
VL_EXPORT void *(* vl_calloc_func )(size_t, size_t)
 Customizable calloc function pointer.
VL_EXPORT void(* vl_free_func )(void *)
 Customizable free function pointer.

Define Documentation

#define VL_CAT ( x,
 )     x ## y

Parameters:
x first argument to be concatenated.
y second argument to be concatenated.
This macro concatenates its arguments into a single lexical unit by means of the ## preprocessor operator. Notice that arguments concatenated by ## are not pre-expanded by the C preprocessor. To macro-expand the arguments and then concatenate them,use VL_XCAT.

See also:
VL_XCAT

Definition at line 85 of file generic.h.

#define VL_ERR_ALLOC   2

Resource allocation error

Definition at line 171 of file generic.h.

#define VL_ERR_BAD_ARG   3

Bad argument or illegal data error

Definition at line 172 of file generic.h.

Referenced by vl_pgm_read_new().

#define VL_ERR_EOF   5

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

Definition at line 174 of file generic.h.

Referenced by vl_sift_process_first_octave(), and vl_sift_process_next_octave().

#define VL_ERR_IO   4

Input/output error

Definition at line 173 of file generic.h.

#define VL_ERR_NO_MORE   5

End-of-sequence

Deprecated:

Definition at line 175 of file generic.h.

#define VL_ERR_OK   0

No error

Definition at line 169 of file generic.h.

Referenced by vl_sift_process_first_octave(), and vl_sift_process_next_octave().

#define VL_ERR_OVERFLOW   1

Buffer overflow error

Definition at line 170 of file generic.h.

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

#define VL_PRINTF   (*vl_printf_func)

The function calls the user customizable printf.

Definition at line 147 of file generic.h.

Referenced by vl_aib_process(), vl_ikm_train(), vl_ikm_train_elkan(), vl_print_host_info(), vl_print_info(), and xmeans().

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

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

Parameters:
x value.
n number of shift positions.
Returns:
x << n .

Definition at line 206 of file generic.h.

Referenced by vl_sift_new(), vl_sift_process_first_octave(), and vl_sift_process_next_octave().

#define VL_STRINGIFY (  )     # x

Parameters:
x value to be stringified.
This macro stringifies the argument x by means of the # prerpocessor operator.

The standard C preprocessor does not prescan arguments which are stringified, so

 #define A B
 char const * str = VL_STRINGIFY(A) ;

initializes str with a pointer to the string "A", which mihgt be unexpected. To fix this issue, you can use VL_XSTRINGIFY.

See also:
VL_XSTRINGIFY

Definition at line 51 of file generic.h.

#define VL_XCAT ( x,
 )     VL_CAT(x,y)

Parameters:
x first argument to be concatenated.
y second argument to be concatenated.
This macro is the same as VL_CAT, except that the arguments are macro expanded before being concatenated.

See also:
VL_CAT

Definition at line 97 of file generic.h.

#define VL_XSTRINGIFY (  )     VL_STRINGIFY(x)

Parameters:
x value to be macro-expanded and converted.
This macro macro-expands the argument x and stringifies the result of the expansion. For instance

 #define A B
 char const * str = VL_STRINGIFY(A) ;

initializes str with a pointer to the string "B".

See also:
VL_STRINGIFY

Definition at line 70 of file generic.h.

#define VL_YESNO (  )     ((x)?"yes":"no")

Parameters:
x boolean to convert. A pointer to either the string "yes" (if x is true) or the string "no".
Example
 VL_PRINTF("Is x true? %s.", VL_YESNO(x))

Definition at line 110 of file generic.h.


Function Documentation

VL_INLINE void * vl_calloc ( size_t  n,
size_t  size 
)

Parameters:
n size of each element in byte.
size size of the array to allocate (number of elements).
The function calls the user-customizable calloc.

Returns:
result of the user-customizable calloc.

Definition at line 243 of file generic.h.

References vl_calloc_func.

Referenced by vl_mser_new(), and vl_quickshift_process().

VL_EXPORT char const* vl_get_version_string (  ) 

---------------------------------------------------------------

Returns:
library version string

Definition at line 251 of file generic.c.

References VL_VERSION_STRING.

Referenced by vl_print_info().

VL_INLINE void * vl_malloc ( size_t  n  ) 

VL_EXPORT void vl_print_info (  ) 

Returns:
library version string

Definition at line 262 of file generic.c.

References vl_get_version_string(), vl_print_host_info(), and VL_PRINTF.

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

Parameters:
ptr buffer to reallocate.
n number of bytes to allocate.
The function calls the user-customizable realloc.

Returns:
result of the user-customizable realloc.

Definition at line 237 of file generic.h.

References vl_realloc_func.

Referenced by vl_sift_detect().

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

Definition at line 340 of file generic.c.

References vl_calloc_func, vl_free_func, vl_malloc_func, and vl_realloc_func.

VL_EXPORT void vl_set_printf_func ( printf_func_t  printf_func  ) 

Parameters:
printf_func pointer to printf. Let print_func be NULL to disable printf.

Definition at line 353 of file generic.c.

References do_nothing_printf(), and vl_printf_func.

VL_EXPORT double vl_toc (  ) 

Returns the processor time elapsed since vl_tic() was called.

Remarks:
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.
Returns:
time in seconds.

Definition at line 391 of file generic.c.


Variable Documentation

VL_EXPORT void*(* vl_calloc_func)(size_t, size_t)

For internal use only.

Referenced by vl_calloc(), and vl_set_alloc_func().

VL_EXPORT void(* vl_free_func)(void *)

For internal use only.

Referenced by vl_set_alloc_func().

VL_EXPORT void*(* vl_malloc_func)(size_t)

For internal use only.

Referenced by vl_malloc(), and vl_set_alloc_func().

VL_EXPORT int(* vl_printf_func)(char const *format,...)

For internal use only.

Referenced by vl_set_printf_func().

VL_EXPORT void*(* vl_realloc_func)(void *, size_t)

For internal use only.

Referenced by vl_realloc(), and vl_set_alloc_func().