LockedAccess provides pointer-like access to a value while holding a
lock. All accessors are rvalue-ref-qualified, restricting usage to
temporaries to prevent accidental lock lifetime extension. A with_ref
method is provided for multi-statement critical sections.
Session::addService now returns a reference to the added Service. This
allows clients to hold a reference for further direct interaction with
the Service object.
This commit also introduces a new Session::createService convenience
method that creates the service and returns a reference to it.
The name "Service" better reflects the general purpose of this class: It
provides *something* (often resource management) to the Session, is
owned by the Session, and receives notifications from the Session when
the controller detaches / is detached, and when the Session is shut
down.
An example of a non-resource-managing Service (to be added in an
upcoming patch) is a detach / shutdown notification service: Clients can
add this service to register arbitrary callbacks to be run on detach /
shutdown. The advantage of this over the current Session detach /
shutdown callback system is that clients can control both the order of
the callbacks, and their order relative to notification of other
services.
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).
handleErrors supports several different handler signatures, including
handlers that take a unique_ptr<T> (where T is a descendant of
ErrorInfoBase) and return an Error: (std::unique_ptr<T>) -> Error. In
this case the handler should be able to create an Error value to wrap
the original ErrorInfoBase object without.
This functionality was not previously tested, and will be used in
upcoming commits. This commit adds the missing test coverage.
All calls to Session::shutdown were enquing their on-shutdown-complete
callbacks in Session's ShutdownInfo struct, but this queue is only
drained once by the thread that initiates shutdown. After the queue is
drained, subsequent calls to Session::shutdown were enquing their
callbacks in a queue that would never be drained.
This patch updates Session::shutdown to check whether shutdown has
completed already and, if so, run the on-shutdown-complete immediately.
This patch also fixes a concurrency bug: Session::shutdownComplete was
accessing SI->OnCompletes outside the session mutex, but this could lead
to corruption of SI->OnCompletes if a concurrent call to
Session::shutdown tried to enqueue a new callback to SI->OnCompletes
concurrently. This has been fixed by moving the SI->OnCompletes queue to
a new variable under the Session mutex, then draining the new queue
outside the mutex. (No testcase yet: this was discovered by observation,
and replicating the bug would depend on timing).
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 unit test was copied from a similar test in llvm, and was still
qualifying calls with 'llvm::'. This was unintended, but happened to
work because LLVM's bit.h is transitively included through LLVM's gtest
headers. Qualifying with 'orc_rt::' tests the intended functions.
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.
When -DORC_RT_ENABLE_EXCEPTIONS=On and -DORC_RT_ENABLE_RTTI=On are
passed we need to ensure that the resulting compiler flags (e.g.
-fexceptions, -frtti for clang/GCC) are appended so that we override any
inherited options (e.g. -fno-exceptions, -fno-rtti) from LLVM.
Updates unit tests to ensure that these compiler options are applied to
them too.
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.
