T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add support for documenting the C API (#1928)

Browse Source 
This commit adds a bit of a skeleton of what it might look like to
document the C API. Today the C API has virtually zero documentation
because the upstream documentation does not exist and we haven't put a
ton of effort into documenting our own extensions. Given that this is
one of the main vectors we expect users to use Wasmtime, we should make
sure it's thoroughly documented!

I've never really done much documentation generation of C myself before,
but I did a bit of searching and Doxygen seems reasonable proficient for
doing this. This commit sets up what it might look like for Doxygen to
be used for the C API. One nice feature of DOxygen is that we can
document the items in `wasm.h` without actually modifying `wasm.h`. For
those purposes a `doc-wasm.h` file was added here which is where we can
put Wasmtime-specific documentation about `wasm.h`.

There's quite a few functions in the C API so I didn't want to get them
all done before getting consensus on this. I've started some skeletons
of documentation for global types in `wasm.h` and also confirmed that
documentation works for our own `wasmtime.h` and such header files. If
this looks good to everyone and it runs reasonable well on CI then I can
spend more time filling out the rest of the documentation.
This commit is contained in:
Alex Crichton
2020-07-01 14:05:18 -05:00
committed by GitHub
parent f24c7e1249
commit d72b330de2
5 changed files with 2849 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
crates/c-api/include/doc-wasm.h Normal file
View File

@@ -0,0 +1,265 @@
/**
* \file wasm.h
*
* Embedding API for WebAssembly.
*
* This API is defined by the upstream wasm-c-api proposal at
* https://github.com/WebAssembly/wasm-c-api. That proposal is in flux but
* Wasmtime intends to be active in its development.
*
* The documentation for this header file is currently defined in the Wasmtime
* project, not in the upstream header file. Some behavior here may be
* Wasmtime-specific and may not be portable to other engines implementing the
* same C API. Also note that not all functionality from the upstream C API is
* implemented in Wasmtime. We strive to provide all symbols as to not generate
* link errors but some functions are unimplemented and will abort the process
* if called.
*
* ### Memory Management
*
* Memory management in the wasm C API is intended to be relatively simple. Each
* individual object is reference counted unless otherwise noted. You can delete
* any object at any time after you no longer need it. Deletion of an object
* does not imply that the memory will be deallocated at that time. If another
* object still internally references the original object then the memory will
* still be alive.
*
* For example you can delete a #wasm_engine_t after you create a #wasm_store_t
* with #wasm_store_new. The engine, however, is still referenced by the
* #wasm_store_t so it will not be deallocated. In essence by calling
* #wasm_engine_delete you're release your own strong reference on the
* #wasm_engine_t, but that's it.
*
* Additionally APIs like #wasm_memory_copy do not actually copy the underlying
* data. Instead they only increment the reference count and return a new
* object. You'll need to still call #wasm_memory_delete (or the corresponding
* `*_delete` function) for each copy of an object you acquire.
*
* ### Thread Safety
*
* All objects are not thread safe unless otherwise noted. This means that all
* objects, once created, cannot be used simultaneously on more than one thread.
*
* In general the split happens at the #wasm_store_t layer. Everything within a
* #wasm_store_t is pinned to that store, and that store is pinned to a thread.
* Objects like #wasm_config_t and #wasm_engine_t, however, are safe to share
* across threads.
*
* Note that if you move a #wasm_store_t between threads this is ok so long as
* you move *all* references within that store to the new thread. If any
* reference lingers on the previous thread then that is unsafe.
*/
/**
* \typedef byte_t
* \headerfile wasm.h
* \brief A type definition for a number that occupies a single byte of data.
*/
/**
* \typedef wasm_byte_t
* \headerfile wasm.h
* \brief A type definition for a number that occupies a single byte of data.
*/
/**
* \typedef float32_t
* \headerfile wasm.h
* \brief A type definition for a 32-bit float.
*/
/**
* \typedef float64_t
* \headerfile wasm.h
* \brief A type definition for a 64-bit float.
*/
/**
* \typedef wasm_name_t
* \headerfile wasm.h
* \brief Convenience for hinting that an argument only accepts utf-8 input.
*/
/**
* \typedef wasm_config_t
* \headerfile wasm.h
* \brief Convenience alias for #wasm_config_t
*/
/**
* \struct wasm_config_t
* \headerfile wasm.h
* \brief Global engine configuration
*
* This structure represents global configuration used when constructing a
* #wasm_engine_t. There are now functions to modify this from wasm.h but the
* wasmtime.h header provides a number of Wasmtime-specific functions to
* tweak configuration options.
*
* This object is created with #wasm_config_new.
*
* Configuration is safe to share between threads. Typically you'll create a
* config object and immediately pass it into #wasm_engine_new_with_config,
* however.
*/
/**
* \fn own wasm_config_t *wasm_config_new(void);
* \brief Creates a new empty configuration object.
*
* The object returned is owned by the caller and will need to be deleted with
* #wasm_config_delete. May return `NULL` if a configuration object could not be
* allocated.
*/
/**
* \fn void wasm_config_delete(own wasm_config_t*);
* \brief Deletes a configuration object.
*/
/**
* \typedef wasm_engine_t
* \headerfile wasm.h
* \brief Convenience alias for #wasm_engine_t
*/
/**
* \struct wasm_engine_t
* \headerfile wasm.h
* \brief Typically global object to create #wasm_store_t from.
*
* An engine is typically global in a program and contains all the configuration
* necessary for compiling wasm code. From an engine you'll typically create a
* #wasm_store_t. Engines are created with #wasm_engine_new or
* #wasm_engine_new_with_config.
*
* An engine is safe to share between threads. Multiple stores can be created
* within the same engine with each store living on a separate thread. Typically
* you'll create one #wasm_engine_t for the lifetime of your program.
*/
/**
* \fn own wasm_engine_t *wasm_engine_new(void);
* \brief Creates a new engine with the default configuration.
*
* The object returned is owned by the caller and will need to be deleted with
* #wasm_engine_delete. This may return `NULL` if the engine could not be
* allocated.
*/
/**
* \fn own wasm_engine_t *wasm_engine_new_with_config(wasm_config_t *);
* \brief Creates a new engine with the specified configuration.
*
* This function will take ownership of the configuration specified regardless
* of the outcome of this function. You do not need to call #wasm_config_delete
* on the argument. The object returned is owned by the caller and will need to
* be deleted with #wasm_engine_delete. This may return `NULL` if the engine
* could not be allocated.
*/
/**
* \fn void wasm_engine_delete(own wasm_engine_t*);
* \brief Deletes an engine.
*/
/**
* \typedef wasm_store_t
* \headerfile wasm.h
* \brief Convenience alias for #wasm_store_t
*/
/**
* \struct wasm_store_t
* \headerfile wasm.h
* \brief A collection of instances and wasm global items.
*
* A #wasm_store_t corresponds to the concept of an [embedding
* store](https://webassembly.github.io/spec/core/exec/runtime.html#store)
*/
/**
* \fn own wasm_store_t *wasm_store_new(wasm_engine_t *);
* \brief Creates a new store within the specified engine.
*
* The object returned is owned by the caller and will need to be deleted with
* #wasm_store_delete. This may return `NULL` if the store could not be
* allocated.
*/
/**
* \fn void wasm_store_delete(own wasm_store_t *);
* \brief Deletes the specified store.
*/
/**
* \struct wasm_byte_vec_t
* \headerfile wasm.h
* \brief A list of bytes
*
* Used to pass data in or pass data out of various functions. The meaning and
* ownership of the bytes is defined by each API that operates on this
* datatype.
*/
/**
* \typedef wasm_byte_vec_t
* \headerfile wasm.h
* \brief Convenience alias for #wasm_byte_vec_t
*/
/**
* \fn void wasm_byte_vec_new_empty(own wasm_byte_vec_t *out);
* \brief Initializes an empty byte vector.
*/
/**
* \fn void wasm_byte_vec_new_uninitialized(own wasm_byte_vec_t *out, size_t);
* \brief Initializes an byte vector with the specified capacity.
*
* This function will initialize the provided vector with capacity to hold the
* specified number of bytes. The `out` parameter must previously not already be
* initialized and after this function is called you are then responsible for
* ensuring #wasm_byte_vec_delete is called.
*/
/**
* \fn void wasm_byte_vec_new(own wasm_byte_vec_t *out, size_t, own wasm_byte_t const[]);
* \brief Copies the specified data into a new byte vector.
*
* This function will copy the provided data into this byte vector. The byte
* vector should not be previously initialized and the caller is responsible for
* calling #wasm_byte_vec_delete after this function returns.
*/
/**
* \fn void wasm_byte_vec_copy(own wasm_byte_vec_t *out, const wasm_byte_vec_t *);
* \brief Copies one vector into a new vector.
*
* Copies the second argument's data into the first argument. The `out` vector
* should not be previously initialized and after this function returns you're
* responsible for calling #wasm_byte_vec_delete.
*/
/**
* \fn void wasm_byte_vec_delete(own wasm_byte_vec_t *);
* \brief Deletes a byte vector.
*
* This function will deallocate the data referenced by the argument provided.
* This does not deallocate the memory holding the #wasm_byte_vec_t itself, it's
* expected that memory is owned by the caller.
*/
/**
* \fn own wasm_memory_t *wasm_memory_copy(const wasm_memory_t *);
* \brief Creates a new reference to the same memory.
*
* The object returned is owned by the caller and will need to be deleted with
* #wasm_memory_delete. This may return `NULL` if the new object could not be
* allocated.
*/
/**
* \fn void wasm_memory_delete(own wasm_memory_t*);
* \brief Deletes a memory object.
*/

26
crates/c-api/include/wasmtime.h
View File

@@ -1,4 +1,13 @@
// WebAssembly C API extension for Wasmtime
/**
* @file
*
* Wasmtime-specific extensions to the WebAssembly C API.
*
* This file contains all of the Wasmtime-specific functions which will not be
* present in other engines. The intention of this file is to augment the
* functionality provided in `wasm.h`.
*/
#ifndef WASMTIME_API_H
#define WASMTIME_API_H
@@ -17,8 +26,23 @@ extern "C" {
\
WASM_API_EXTERN void wasmtime_##name##_delete(own wasmtime_##name##_t*);
/**
* \brief Errors generated by Wasmtime.
*
* This opaque type represents an error that happened as part of one of the
* functions below. Errors primarily have an error message associated with them
* at this time, which you can acquire by calling #wasmtime_error_message.
*/
WASMTIME_DECLARE_OWN(error)
/**
* \brief Returns the string description of this error.
*
* This will "render" the error to a string and then return the string
* representation of the error to the caller. The `message` argument should be
* uninitialized before this function is called and the caller is responsible
* for deallocating it with #wasm_byte_vec_delete afterwards.
*/
WASM_API_EXTERN void wasmtime_error_message(
const wasmtime_error_t *error,
own wasm_name_t *message