Session::waitForShutdown is a convenience wrapper around the
asynchronous Session::shutdown call. The previous
Session::waitForShutdown call waited on a std::condition_variable to
signal the end of shutdown, but it's easier to just embed a std::promise
in a callback to the asynchronous shutdown method.
This commit introduces a C interface for the ORC runtime's Error
handling system, enabling C clients and language bindings to work with
ORC errors.
The ORC_RT_C_ABI macro applies __attribute__((visibility("default")))
(on platforms that support it), ensuring C API symbols are exported when
building the ORC runtime as a shared library. In the future I expect
that this will be extended to support other platforms (e.g. dllexport on
Windows).
In e838f27e0f3 the EndianTest.cpp unittest was updated to avoid using
`llvm::rotl` function, but the corresponding `orc_rt::rotl` function had
not been implemented yet.
This commit implements orc_rt::rotl, orc_rt::rotr, and
orc_rt::has_single_bit by copying their definitions from the
corresponding LLVM header (llvm-project/llvm/include/llvm/ADT/bit.h).
Unit tests for these functions are also copied from their LLVM
counterparts.
Thanks to @jaredwy for spotting this!
The WrapperFunctionBuffer(orc_rt_WrapperFunctionBuffer) constructor
takes ownership of the underlying buffer (if one exists). Making the
constructor explicit makes this clearer at the call site.
This mirrors a similar change to the LLVM-side API in dec5d663745.
QueueingTaskDispatcher adds Tasks to a the back of a double ended queue
that is accessible to clients via the `pop_back` and `pop_front`
methods. Clients can manually take and run tasks, or call
`runLIFOUntilEmpty` or `runFIFOUntilEmpty` to run tasks until the queue
is empty.
QueueingTaskDispatcher is intended for use in unit tests, and as a
foundation for blocking convenience APIs in environments without
threads. QueueingTaskDispatcher should generally be avoided, and
ThreadPoolTaskDispatcher preferred, where threads are available.
Custom error types (ErrorInfoBase subclasses) should use ErrorExtends as
of 8f51da369e6. Adding a static_assert allows us to enforce that at
compile-time.
The ORC runtime needs to work in diverse codebases, both with and
without C++ exceptions enabled (e.g. most LLVM projects compile with
exceptions turned off, but regular C++ codebases will typically have
them turned on). This introduces a tension in the ORC runtime: If a C++
exception is thrown (e.g. by a client-supplied callback) it can't be
ignored, but orc_rt::Error values will assert if not handled prior to
destruction. That makes the following pattern fundamentally unsafe in
the ORC runtime:
```
if (auto Err = orc_rt_operation(...)) {
log("failure, bailing out"); // <- may throw if exceptions enabled
// Exception unwinds stack before Error is handled, triggers Error-not-checked
// assertion here.
return Err;
}
```
We can resolve this tension by preventing any exceptions from unwinding
through ORC runtime stack frames. We can do this while preserving
exception *values* by catching all exceptions (using `catch (...)`) and
capturing their values as a std::exception_ptr into an Error.
This patch adds APIs to simplify conversion between C++ exceptions and
Errors. These APIs are available only when enabled when the ORC runtime
is configured with ORC_RT_ENABLE_EXCEPTIONS=On (the default).
- `ExceptionError` wraps a std::exception_ptr.
- `runCapturingExceptions` takes a T() callback and converts any
exceptions thrown by the body into Errors. If T is Expected or Error
already then runCapturingExceptions returns the same type. If T is void
then runCapturingExceptions returns an Error (returning Error::success()
if no exception is thrown). If T is any other type then
runCapturingExceptions returns an Expected<T>.
- A new Error::throwOnFailure method is added that converts failing
values into thrown exceptions according to the following rules:
1. If the Error is of type ExceptionError then std::rethrow_exception is
called on the contained std::exception_ptr to rethrow the original
exception value.
2. If the Error is of any other type then std::unique_ptr<T> is thrown
where T is the dynamic type of the Error.
These rules allow exceptions to be propagated through the ORC runtime as
Errors, and for ORC runtime errors to be converted to exceptions by
clients.
Clients should be able to build the ORC runtime with or without
exceptions/RTTI, and this choice should be able to be made independently
of the corresponding settings for LLVM (e.g. it should be fine to build
LLVM with exceptions/RTTI disabled, and orc-rt with them enabled).
The orc-rt-c/config.h header will provide C defines that can be used by
both the ORC runtime and API clients to determine the value of the
options.
Future patches should build on this work to provide APIs that enable
some interoperability between the ORC runtime's error return mechanism
(Error/Expected) and C++ exceptions.
Using CallableTraitsHelper simplifies the expression of
ErrorHandlerTraits, which is responsible for running handlers based on
their argument and return types.
ControllerAccess provides an abstract interface for bidirectional RPC
between the executor (running JIT'd code) and the controller (containing
the llvm::orc::ExecutionSession). ControllerAccess implementations are
expected to implement IPC / RPC using a concrete communication method
(shared memory, pipes, sockets, native system IPC, etc).
Calls from executor to controller are made via callController, with
"handler tags" (addresses in the executor) specifying the target handler
in the controller. A handler must be associated in the controller with
the given tag for the call to succeed. This ensures that only registered
entry points in the controller can be used, and avoids leaking
controller addresses into the executor.
Calls in both directions are to "wrapper functions" that take a buffer
of bytes as input and return a buffer of bytes as output. In the ORC
runtime these must be `orc_rt_WrapperFunction`s (see
Session::handleWrapperCall). The interpretation of the byte buffers is
up to the wrapper functions: the ORC runtime imposes no restrictions on
how the bytes are to be interpreted.
ControllerAccess objects may be detached from the Session prior to
Session shutdown, in which case no further calls may be made in either
direction, and any pending results (from calls made that haven't
returned yet) should return errors. If the ControllerAccess class is
still attached at Session shutdown time it will be detached as part of
the shutdown process. The ControllerAccess::disconnect method must
support concurrent entry on multiple threads, and all callers must block
until they can guarantee that no further calls will be received or
accepted.
Moves all Session member variables dedicated to shutdown into a new
ShutdownInfo struct, and uses the presence / absence of this struct as
the flag to indicate that we've entered the "shutting down" state. This
simplifies the implementation of the shutdown process.
Introduces the Task and TaskDispatcher interfaces (TaskDispatcher.h),
ThreadPoolTaskDispatcher implementation (ThreadPoolTaskDispatch.h), and
updates Session to include a TaskDispatcher instance that can be used to
run tasks.
TaskDispatcher's introduction is motivated by the need to handle calls
to JIT'd code initiated from the controller process: Incoming calls will
be wrapped in Tasks and dispatched. Session shutdown will wait on
TaskDispatcher shutdown, ensuring that all Tasks are run or destroyed
prior to the Session being destroyed.
This argument serves as an opaque id (outside the ControllerAccess
object) for a call to a wrapper function. I expect that most
ControllerAccess implementations will want to use this argument as a
sequence number (plain integer), for which uint64_t will be a better fit
than void*. For ControllerAccess implementations that want to use a
pointer, uint64_t should be sufficiently large.
Can be used to test that one address range is fully contained within
another. This is an orc-rt counterpart to aa731e19045, which added the
same operation to llvm::orc::ExecutorAddrRange.
7381558ef8b renamed the FinalizeRequest type to InitializeRequest. This commit
updates InitializeRequest variable names to follow suit ("FR"s become "IR"s).
This commit renames the "finalize" operation to "initialize", and
"deallocate" to "deinitialize".
The new names are chosen to better fit the point of view of the
ORC-runtime and executor-process: After memory is *reserved* it can be
*initialized* with some content, and *deinitialized* to return that
memory to the reserved region.
This seems more understandable to me than the original scheme, which
named these operations after the controller-side JITLinkMemoryManager
operations that they partially implemented. I.e.
SimpleNativeMemoryMap::finalize implemented the final step of
JITLinkMemoryManager::finalize, initializing the memory in the executor;
and SimpleNativeMemoryMap::deallocate implemented the final step of
JITLinkMemoryManager::deallocate, running dealloc actions and releasing
the finalized region.
The proper way to think of the relationship between these operations now
is that:
1. The final step of finalization is to initialize the memory in the
executor.
2. The final step of deallocation is to deinitialize the memory in the
executor.
In an ORC JIT it's common for multiple memory regions to be deallocated
at once, e.g. when a ResourceTracker covering multiple object files is
removed. This commit adds SimpleNativeMemoryMap::deallocateMultiple and
SimpleNativeMemoryMap::releaseMultiple APIs that can be used to reduce
the number of calls (and consequently IPC messages in cross-process
setups) in these cases.
Adding these operations will make it easier to write an
llvm::orc::MemoryMapper class that can use SimpleNativeMemoryMap as a
backend.
This replaces SPS transparent conversion for pointers. Transparent
conversion only applies to argument/return types, not nested types. We
want to be able to serialize / deserialize structs containing pointers.
We may need to replace this in the near future with a new SPSPointer tag
type, since SPSExecutorAddr is meant to be serialization for pure
addresses, and pointers may carry other information (e.g. tag bits), but
we can do that in a follow-up commit.
This commit aims to align SimpleNativeMemoryMap::FinalizeRequest::Segment with
llvm::orc::tpctypes::SegFinalizeRequest. This will simplify construction of a
new LLVM JITLinkMemoryManager that's capable of using SimpleNativeMemoryMap as
a backend.
SPS deserialization for span<const char> produces a value that points
directly into the argument buffer for efficiency. This was broken by an
unnecessary std::move of the buffer inside WrapperFunction, which this
commit removes.
An orc-rt Session contains a JIT'd program, managing resources and
communicating with a remote JIT-controller instance (expected to be an
orc::ExecutionSession, though this is not required).
SimpleNativeMemoryMap is a memory allocation backend for use with ORC.
It can...
1. Reserve slabs of address space.
2. Finalize regions of memory within a reserved slab: copying content
into requested addresses, applying memory protections, running
finalization actions, and storing deallocation actions to be run by
deallocate.
3. Deallocate finalized memory regions: running deallocate actions and,
if possible, making memory in these regions available for use by future
finalization operations. (Some systems prohibit reuse of executable
memory. On these systems deallocated memory is no longer usable within
the process).
4. Release reserved slabs. This runs deallocate for any
not-yet-deallocated finalized regions, and then (if possible) returns
the address space to system. (On systems that prohibit reuse of
executable memory parts of the released address space may be permanently
unusable by the process).
SimpleNativeMemoryMap is intended primarily for use by
llvm::orc::JITLinkMemoryManager implementations to allocate JIT'd code
and data.
The ResourceManager interface can be used to implement ownership for resources
allocated to JIT'd code, e.g. memory and metadata registrations (frame info,
language runtime metadata, etc.).
Resources can be *deallocated*, meaning that they should be cleaned up (memory
released, registrations deregistered, etc.), or they can be *detached*, meaning
that cleanup should be performed automatically when the ResourceManager itself
is destroyed.
The intent is to allow JIT'd code to continue running after the
llvm::orc::ExecutionSession that produced it is disconnected / destroyed.
WrapperFunction::handleWithAsyncMethod can be used to wrap asynchronous
methods (void methods whose first arguments are Return callbacks) for
use with WrapperFunction::handle.
WrapperFunction::handleWithSyncMethod can be used to wrap regular
(non-asynchronous) methods for use with WrapperFunction::handle.
Both variants return function objects that take a Return callback as
their first argument, and an ExecutorAddr representing the address of
the instance to call the object on. For asynchronous methods the
resulting function object (AsyncMethod<method-ptr>) forwards the Return
callback through to the method. For synchronous methods the method is
called and the result passed to the Return callback.
This adds support for WrapperFunction::handle handlers that take their
arguments by reference, rather than by value.
This commit also reduces the number of temporary objects created to
support SPS-transparent conversion in SPSWrapperFunction.
This commit aims to reduce boilerplate by adding transparent conversion
between Error/Expected types and their SPS-serializable counterparts
(SPSSerializableError/SPSSerializableExpected). This allows
SPSWrapperFunction calls and handles to be written in terms of
Error/Expected directly.
This functionality can also be extended to transparently convert between
other types. This may be used in the future to provide conversion
between ExecutorAddr and native pointer types.
Serializers only need to provide two methods now, rather than four. The
first method should return an argument serializer / deserializer, the
second a result value serializer / deserializer. The interfaces for
these are now more uniform (deserialize now returns a tuple, rather than
taking its output location(s) by reference). The intent is to simplify
Serializer helper code. NFCI.
CallableTraitsHelper identifies the return type and argument types of a
callable type and passes those to an implementation class template to
operate on.
The CallableArgInfo utility uses CallableTraitsHelper to provide
typedefs for the return type and argument types (as a tuple) of a
callable type.
In WrapperFunction.h, the detail::WFCallableTraits utility is rewritten
in terms of CallableTraitsHandler (and renamed to WFHandlerTraits).
These will be used in upcoming RPC support patches where the outer
Expected value captures any RPC-infrastructure errors, and the inner
Error is returned from the romet call (i.e. the remote handler's return
type is Error).
Adds an overload of toSPSSerializableExpected that takes a plain T value
and returns an SPSSerializableExpected<T>. This will reduce some
boilerplate when creating SPSSerializableExpected values.
After the recent change to hoist std::decay_t (cd8f47b2d4e) we were
forcing move-initialization of the callable type. This commit restores
perfect forwarding so that we copy-initialize where expected.
