foundation.h File Reference

#include <vgl/base.h>

Go to the source code of this file.

Classes
struct	vgl_allocator_interface
struct	vgl_io_read
struct	vgl_io_interface
struct	vgl_io_request_create_info
struct	vgl_task_interface

Macros
#define	VGL_ALLOCATOR_INTERFACE_VERSION   1
#define	VGL_IO_SIZE_TO_END   UINT64_MAX
#define	VGL_IO_INTERFACE_VERSION   1
#define	VGL_TASK_INTERFACE_VERSION   1

Typedefs
typedef void(*	vgl_log_fn) (void *user_data, vgl_log_level level, const char *message)
typedef struct vgl_io_request	vgl_io_request
typedef void(*	vgl_io_complete_fn) (void *user_data, vgl_result result, const void *data, size_t size)
typedef void(*	vgl_task_fn) (void *user_data)

Enumerations
enum	vgl_log_level {   VGL_LOG_LEVEL_DEFAULT = 0 , VGL_LOG_LEVEL_ERROR = 1 , VGL_LOG_LEVEL_WARNING = 2 , VGL_LOG_LEVEL_INFO = 3 ,   VGL_LOG_LEVEL_DEBUG = 4 , VGL_LOG_LEVEL_MAX_ENUM = 0x7FFFFFFF }

Functions
vgl_result	vgl_io_request_complete (vgl_io_request *request, vgl_result result, const void *data, size_t size)
vgl_result	vgl_io_request_create (const vgl_io_request_create_info *info, vgl_io_request **out_request)

Macro Definition Documentation

VGL_ALLOCATOR_INTERFACE_VERSION

#define VGL_ALLOCATOR_INTERFACE_VERSION   1

VGL_IO_SIZE_TO_END

#define VGL_IO_SIZE_TO_END   UINT64_MAX

Size meaning "to the end of the file".

VGL_IO_INTERFACE_VERSION

#define VGL_IO_INTERFACE_VERSION   1

VGL_TASK_INTERFACE_VERSION

#define VGL_TASK_INTERFACE_VERSION   1

Typedef Documentation

vgl_log_fn

typedef void(* vgl_log_fn) (void *user_data, vgl_log_level level, const char *message)

Receives a log message.

Parameters

user_data	The pointer registered with the callback.
level	Severity of the message.
message	UTF-8 text without a trailing newline, valid only during the call.

Thread safety

Any thread. Must be thread-safe if a task callback is installed.

vgl_io_request

typedef struct vgl_io_request vgl_io_request

A read the library has asked the host to perform.

vgl_io_complete_fn

typedef void(* vgl_io_complete_fn) (void *user_data, vgl_result result, const void *data, size_t size)

Receives the completion of a request made with vgl_io_request_create: the result, and on success the bytes read, valid only during the call.

Thread safety: called on the thread that completes the request, inside vgl_io_request_complete.

vgl_task_fn

typedef void(* vgl_task_fn) (void *user_data)

A unit of work, run once with the user data it was submitted with.

Thread safety: task thread.

Enumeration Type Documentation

vgl_log_level

enum vgl_log_level

Severity of a log message, and the minimum level a context reports.

Enumerator
VGL_LOG_LEVEL_DEFAULT	As a minimum level, selects VGL_LOG_LEVEL_WARNING. Never the level of a message.
VGL_LOG_LEVEL_ERROR
VGL_LOG_LEVEL_WARNING
VGL_LOG_LEVEL_INFO
VGL_LOG_LEVEL_DEBUG
VGL_LOG_LEVEL_MAX_ENUM

Function Documentation

vgl_io_request_complete()

vgl_result vgl_io_request_complete	(	vgl_io_request *	request,
		vgl_result	result,
		const void *	data,
		size_t	size
	)

Completes an I/O request.

The library copies data before the function returns, so the host may free it afterwards. Every call with a non-null request consumes it, whatever the call returns: the handle is invalid once the function returns, and the request must not be completed again.

Parameters

request	The request, from vgl_io_interface.read, or one made with vgl_io_request_create, whose callback then receives the result.
result	VGL_RESULT_SUCCESS if data holds what was read; otherwise the error that kept it from being read, such as VGL_RESULT_NOT_FOUND, VGL_RESULT_IO_ERROR or VGL_RESULT_CANCELLED. Not a positive status.
data	The bytes read, or null if result is not VGL_RESULT_SUCCESS.
size	Number of bytes in data.

Return values

VGL_RESULT_SUCCESS	The completion was queued.
VGL_RESULT_OUT_OF_MEMORY	The data could not be copied; the request fails with this result.
VGL_RESULT_INVALID_ARGUMENT	request is null, which does nothing; or data is null with a non-zero size, or result is a positive status: the request fails with this result.

Thread safety

Free-threaded. May be called from inside vgl_io_interface.read.

vgl_io_request_create()

vgl_result vgl_io_request_create	(	const vgl_io_request_create_info *	info,
		vgl_io_request **	out_request
	)

Creates a request whose completion goes to a callback rather than to a context, so that an I/O interface can pass a read on to another one and handle what it delivers, as a cache or any other wrapper does (design document, section 7.5). The request goes to another interface's read with a vgl_io_read the creator keeps valid until completion, and is completed exactly once with vgl_io_request_complete, which calls complete and frees the request. A request that never reaches a read is freed by completing it too.

Parameters

info	The callback and its user data, and the allocator.
out_request	Receives the request.

Return values

VGL_RESULT_SUCCESS	The request was created.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, or info has no complete callback or an invalid allocator.
VGL_RESULT_NOT_SUPPORTED	info has fields from a newer version set.
VGL_RESULT_VERSION_MISMATCH	The allocator interface has an unknown version.
VGL_RESULT_OUT_OF_MEMORY	Allocation failed.

Thread safety

Free-threaded.