 |
vgl 1.0.0
Virtual Globe Library: API reference
|
|
vgl 1.0.0
Virtual Globe Library: API reference
|
Go to the source code of this file.
Classes | |
| struct | vgl_thread_pool_create_info |
| struct | vgl_file_reader_create_info |
| struct | vgl_http_reader_create_info |
| struct | vgl_disk_cache_create_info |
| struct | vgl_disk_cache_statistics |
Macros | |
| #define | VGL_DEFAULTS_API |
Typedefs | |
| typedef struct vgl_thread_pool | vgl_thread_pool |
| typedef struct vgl_file_reader | vgl_file_reader |
| typedef struct vgl_http_reader | vgl_http_reader |
| typedef struct vgl_disk_cache | vgl_disk_cache |
| #define VGL_DEFAULTS_API |
| typedef struct vgl_thread_pool vgl_thread_pool |
A fixed set of worker threads that run tasks in the order they were submitted.
| typedef struct vgl_file_reader vgl_file_reader |
Reads files for the I/O interface. URIs are UTF-8 paths, absolute or relative to the working directory, with an optional "file://" prefix; they are not percent-decoded. A file that does not exist completes with VGL_RESULT_NOT_FOUND, other failures with VGL_RESULT_IO_ERROR.
| typedef struct vgl_http_reader vgl_http_reader |
Reads packs from a web server for the I/O interface, with HTTP range requests (design document, section 8.6), so that any server, CDN or object store that serves range requests can hold packs. It is built on libcurl, when vgl is built with VGL_DEFAULTS_HTTP; without it, vgl_http_reader_create reports VGL_RESULT_NOT_SUPPORTED. URIs starting with "http://" or "https://" are read over HTTP, others through the fallback interface the create info names.
Reads run on one thread of the reader's own, which overlaps them over a few connections per server, and complete from it. A missing file (404 or 410) completes with VGL_RESULT_NOT_FOUND, a range past the end of the file (416) with no bytes, as the file reader does, and other failures, timeouts among them, with VGL_RESULT_IO_ERROR. A server that ignores range requests sends the whole file, of which the reader keeps the range.
libcurl's own allocations do not go through the allocator, which serves the reader and the data it delivers.
On Emscripten, the reader is built on the browser's fetch instead, with VGL_DEFAULTS_HTTP and no library, and needs no thread: fetches start and finish on the main thread, between the page's frames, and reads that arrive on other threads are passed to it. Reads that fail without an answer are tried again, a few times. Without a fallback, URIs that are not HTTP are fetched too, relative to the page's address. The browser chooses the connections and the User-Agent header, and allocates the data delivered.
| typedef struct vgl_disk_cache vgl_disk_cache |
Keeps what another I/O interface reads from web servers in a directory, so that areas seen once load again without the network, and offline (design document, section 8.6). It wraps the interface: put it between a context and an HTTP reader, or a host's own network layer. Only "http://" and "https://" URIs are cached; others go straight to the wrapped interface.
Each read is an entry, by its URI and byte range. Shards are kept as they are, since their names hold a digest of their content (pack format, section 5.2): a cached shard is never stale, and is read from the disk. A manifest (pack.vglm) changes in place when a pack is rebaked, so it is always read from the server, and from the disk only when the server cannot be reached. When the entries exceed the budget, the least recently used go.
Cancelling a read completes it with VGL_RESULT_CANCELLED at once; a download in progress goes on and is stored. Entries are written to a temporary name and renamed, so a cache left by a crash holds only whole entries, and one that does not match its key or checksum is read again. One process at a time may use a directory.
| vgl_result vgl_thread_pool_create | ( | const vgl_thread_pool_create_info * | info, |
| vgl_thread_pool ** | out_pool | ||
| ) |
Creates a thread pool and starts its threads.
| info | Optional. Null means all defaults. |
| out_pool | Receives the pool. |
| VGL_RESULT_SUCCESS | The pool was created. |
| VGL_RESULT_INVALID_ARGUMENT | out_pool is null, or info is invalid. |
| VGL_RESULT_VERSION_MISMATCH | The allocator interface has an unknown version. |
| VGL_RESULT_NOT_SUPPORTED | info has fields from a newer version set. |
| VGL_RESULT_OUT_OF_MEMORY | Allocation failed, or a thread could not be started. |
| vgl_result vgl_thread_pool_destroy | ( | vgl_thread_pool * | pool | ) |
Runs the tasks still queued, then stops the threads and frees the pool. Every task the pool accepted runs exactly once.
| pool | The pool, or null. |
| VGL_RESULT_SUCCESS | Always. |
| vgl_result vgl_thread_pool_task_interface_get | ( | vgl_thread_pool * | pool, |
| vgl_task_interface * | out_interface | ||
| ) |
Gets a task interface that submits to the pool, for vgl_context_create_info.tasks. The interface has no destroy callback: the pool must outlive every context that uses it.
| pool | The pool. |
| out_interface | Receives the interface. |
| VGL_RESULT_SUCCESS | The interface was written. |
| VGL_RESULT_INVALID_ARGUMENT | A pointer is null. |
| vgl_result vgl_file_reader_create | ( | const vgl_file_reader_create_info * | info, |
| vgl_file_reader ** | out_reader | ||
| ) |
Creates a file reader.
| info | Optional. Null means all defaults: reading without a pool. |
| out_reader | Receives the reader. |
| VGL_RESULT_SUCCESS | The reader was created. |
| VGL_RESULT_INVALID_ARGUMENT | out_reader is null, or info is invalid. |
| VGL_RESULT_VERSION_MISMATCH | The allocator interface has an unknown version. |
| VGL_RESULT_NOT_SUPPORTED | info has fields from a newer version set. |
| VGL_RESULT_OUT_OF_MEMORY | Allocation failed. |
| vgl_result vgl_file_reader_destroy | ( | vgl_file_reader * | reader | ) |
Waits for the reads in progress, then frees the reader. Its pool must still exist.
| reader | The reader, or null. |
| VGL_RESULT_SUCCESS | Always. |
| vgl_result vgl_file_reader_io_interface_get | ( | vgl_file_reader * | reader, |
| vgl_io_interface * | out_interface | ||
| ) |
Gets an I/O interface that reads through the reader, for vgl_context_create_info.io. The interface has no destroy callback: the reader must outlive every context that uses it.
| reader | The reader. |
| out_interface | Receives the interface. |
| VGL_RESULT_SUCCESS | The interface was written. |
| VGL_RESULT_INVALID_ARGUMENT | A pointer is null. |
| vgl_result vgl_http_reader_create | ( | const vgl_http_reader_create_info * | info, |
| vgl_http_reader ** | out_reader | ||
| ) |
Creates an HTTP reader and starts its thread.
| info | Optional. Null means all defaults. |
| out_reader | Receives the reader. |
| VGL_RESULT_SUCCESS | The reader was created. |
| VGL_RESULT_INVALID_ARGUMENT | out_reader is null, or info is invalid: the timeout is negative or not finite, or the fallback has no read callback or an unknown version. |
| VGL_RESULT_NOT_SUPPORTED | vgl was built without VGL_DEFAULTS_HTTP, or 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. |
| VGL_RESULT_IO_ERROR | libcurl could not be set up. |
| vgl_result vgl_http_reader_destroy | ( | vgl_http_reader * | reader | ) |
Cancels the reads in progress, which complete with VGL_RESULT_CANCELLED, stops the reader's thread and frees the reader.
| reader | The reader, or null. |
| VGL_RESULT_SUCCESS | Always. |
| vgl_result vgl_http_reader_io_interface_get | ( | vgl_http_reader * | reader, |
| vgl_io_interface * | out_interface | ||
| ) |
Gets an I/O interface that reads through the reader, for vgl_context_create_info.io. The interface has no destroy callback: the reader must outlive every context that uses it.
| reader | The reader. |
| out_interface | Receives the interface. |
| VGL_RESULT_SUCCESS | The interface was written. |
| VGL_RESULT_INVALID_ARGUMENT | A pointer is null. |
| vgl_result vgl_disk_cache_create | ( | const vgl_disk_cache_create_info * | info, |
| vgl_disk_cache ** | out_cache | ||
| ) |
Creates a disk cache, reading what the directory already holds.
| info | The directory, the source and the budget. |
| out_cache | Receives the cache. |
| VGL_RESULT_SUCCESS | The cache was created. |
| VGL_RESULT_INVALID_ARGUMENT | A pointer is null, or info has no directory or source, or the source has no read callback. |
| VGL_RESULT_NOT_SUPPORTED | info has fields from a newer version set. |
| VGL_RESULT_VERSION_MISMATCH | The source or allocator interface has an unknown version. |
| VGL_RESULT_OUT_OF_MEMORY | Allocation failed. |
| VGL_RESULT_IO_ERROR | The directory could not be created or read. |
| vgl_result vgl_disk_cache_destroy | ( | vgl_disk_cache * | cache | ) |
Destroys the cache, after the disk work in progress, so that what was read is stored. Reads of the source that are still in progress complete later, without storing what they read; the source and the pool must outlive them.
| cache | The cache, or null. |
| VGL_RESULT_SUCCESS | Always. |
| vgl_result vgl_disk_cache_io_interface_get | ( | vgl_disk_cache * | cache, |
| vgl_io_interface * | out_interface | ||
| ) |
Gets an I/O interface that reads through the cache, for vgl_context_create_info.io. The interface has no destroy callback: the cache must outlive every context that uses it.
| cache | The cache. |
| out_interface | Receives the interface. |
| VGL_RESULT_SUCCESS | The interface was written. |
| VGL_RESULT_INVALID_ARGUMENT | A pointer is null. |
| vgl_result vgl_disk_cache_statistics_get | ( | vgl_disk_cache * | cache, |
| vgl_disk_cache_statistics * | out_statistics | ||
| ) |
Gets the cache's statistics.
| cache | The cache. |
| out_statistics | Receives them, an output structure (docs/c-api.md, section 8.4): set its struct_size, at least 8. |
| VGL_RESULT_SUCCESS | The statistics were written. |
| VGL_RESULT_INVALID_ARGUMENT | A pointer is null, or struct_size is below 8. |
| vgl_result vgl_disk_cache_clear | ( | vgl_disk_cache * | cache | ) |
Removes every entry. Reads in progress complete, and may store what they read.
| cache | The cache. |
| VGL_RESULT_SUCCESS | The entries were removed. |
| VGL_RESULT_INVALID_ARGUMENT | cache is null. |
| VGL_RESULT_OUT_OF_MEMORY | Allocation failed; nothing was removed. |
| VGL_RESULT_IO_ERROR | Some entries could not be removed; the others were. |
1.9.8