API functions exposed via msgpack-rpc now fall into two categories:
- async functions, which are executed as soon as the request is parsed
- sync functions, which are invoked in nvim main loop when processing the
`K_EVENT special key
Only a few functions which can be safely executed in any context are marked as
async.
- Expose more logging control from the log.c module(get log stream and omit
newlines)
- Remove logging from the generated functions in msgpack-gen.lua
- Refactor channel.c/helpers.c to log every msgpack-rpc payload using
msgpack_object_print(a helper function from msgpack.h)
- Remove the api_stringify function, it was only useful for logging msgpack-rpc
which is now handled by msgpack_object_print.
Since all API functions now run immediately after a msgpack-rpc request is
parsed by libuv callbacks, a mechanism was added to override this behavior and
allow certain functions to run in Nvim main loop.
The mechanism is simple: Any API function tagged with the FUNC_ATTR_DEFERRED (a
"dummy" attribute only used by msgpack-gen.lua) will be called when Nvim main
loop receives a K_EVENT key.
To implement this mechanism it was necessary some restructuration on the
msgpack-rpc modules, especially in the msgpack-gen.lua script.
Adapt gendeclarations.lua/msgpack-gen.lua to allow the `ArrayOf(...)` and
`DictionaryOf(...)` types in function headers. These are simple macros that
expand to Array and Dictionary respectively, but the information is kept in the
metadata object, which is useful for building clients in statically typed
languages.
Instead of building all metadata from msgpack-gen.lua, we now merge the
generated part with manual information(such as types and features). The metadata
is accessible through the api method `vim_get_api_info`.
This was done to simplify the generator while also increasing flexibility(by
being able to add more metadata)
Enhance msgpack-gen.lua to extract custom api type codes from the ObjectType
enum in api/private/defs.h. The type information is made available from the api
metadata and clients can use to correctly serialize/deserialize these types
using msgpack EXT type.
A new method is now exposed via msgpack-rpc: "get_api_metadata". This method has
the same job as the old method '0', it returns an object with API metadata for
use by generators.
There's one difference in the return value though: instead of returning a
string containing another serialized msgpack document, the metadata object is
returned directly(a separate deserialization step by clients is not required).
Use Map(String, rpc_method_handler_fn) for storing/retrieving rpc method
handlers in msgpack_rpc_init and msgpack_rpc_dispatch.
Also refactor serialization/validation functions in the
msgpack_rpc.c/msgpack_rpc_helpers.c modules to accept the new STR and BIN types.
Using msgpack v5 will let nvim be more compatible with msgpack libraries for
other platforms.
This also replaces "raw" references by "bin" which is the new name for msgpack
binary data type
Also changed the default log level to INFO so developers won't end up with big
log files without asking explicitly(DLOG statements were placed in really "hot"
code)
- Initialize variables before validating argument count to remove possibility of
freeing uninitialized pointers
- Set the error when the argument count validation fails
This simplifies the generated msgpack_rpc_dispatch() function, separates the
code for each RPC method more clearly and allows easy implementation of
alternative dispatching methods (e.g. string method id dispatch).
This is how API dispatching worked before this commit:
- The generated `msgpack_rpc_dispatch` function receives a the `msgpack_packer`
argument.
- The response is incrementally built while validating/calling the API.
- Return values/errors are also packed into the `msgpack_packer` while the
final response is being calculated.
Now the `msgpack_packer` argument is no longer provided, and the
`msgpack_rpc_dispatch` function returns `Object`/`Error` values to
`msgpack_rpc_call`, which will use those values to build the response in a
single pass.
This was done because the new `channel_send_call` function created the
possibility of having recursive API invocations, and this wasn't possible when
sharing a single `msgpack_sbuffer` across call frames(it was shared implicitly
through the `msgpack_packer` instance).
Since we only start to build the response when the necessary information has
been computed, it's now safe to share a single `msgpack_sbuffer` instance
across all channels and API invocations.
Some other changes also had to be performed:
- Handling of the metadata discover was moved to `msgpack_rpc_call`
- Expose more types as subtypes of `Object`, this was required to forward the
return value from `msgpack_rpc_dispatch` to `msgpack_rpc_call`
- Added more helper macros for casting API types to `Object`
any
- The 'stripdecls.py' script replaces declarations in all headers by includes to
generated headers.
`ag '#\s*if(?!ndef NEOVIM_).*((?!#\s*endif).*\n)*#ifdef INCLUDE_GENERATED'`
was used for this.
- Add and integrate gendeclarations.lua into the build system to generate the
required includes.
- Add -Wno-unused-function
- Made a bunch of old-style definitions ANSI
This adds a requirement: all type and structure definitions must be present
before INCLUDE_GENERATED_DECLARATIONS-protected include.
Warning: mch_expandpath (path.h.generated.h) was moved manually. So far it is
the only exception.
- Leave src as include dir (for includes to recognize 'nvim/' prefix).
- Change subdirectory from src to src/nvim.
- Fix msgpack generation.
- Fix some other paths to new locations.
- Split functions with multiple files in the 'api' subdirectory
- Move/Add more types in the 'api/defs.h' header
- Add more prototypes
- Refactor scripts/msgpack-gen.lua
- Move msgpack modules to 'os' subdirectory
This adds a lua script which parses the contents of 'api.h'. After the api is
parsed into a metadata table. After that, it will generate:
- A msgpack blob for the metadata table. This msgpack object contains everything
scripting engines need to generate their own wrappers for the remote API.
- The `msgpack_rpc_dispatch` function, which takes care of validating msgpack
requests, converting arguments to C types and passing control to the
appropriate 'api.h' function. The result is then serialized back to msgpack
and returned to the client.
This approach was used because:
- It automatically modifies `msgpack_rpc_dispatch` to reflect API changes.
- Scripting engines that generate remote call wrappers using the msgpack
metadata will also adapt automatically to API changes
