Introduce common infrastructure for runtimes that determines compiler
resource path locations. These variables introduced are:
* RUNTIMES_OUTPUT_RESOURCE_DIR
* RUNTIMES_INSTALL_RESOURCE_PATH
That contain the location for the compiler resource path (typically
`lib/clang/<version>`) in the build tree and the install tree (the
latter relative to CMAKE_INSTALL_PREFIX).
Additionally, define
* RUNTIMES_OUTPUT_RESOURCE_LIB_DIR
* RUNTIMES_INSTALL_RESOURCE_LIB_PATH
as for the location of clang/flang version-locked libraries (typically
`lib${LLVM_LIBDIR_SUFFIX}/<targer-triple>`, but also depends on `APPLE`
and `LLVM_ENABLE_PER_TARGET_RUNTIME_DIR`). This code is moved from
flang-rt and initially becomes its only user.
Refactored out of #171610 as requested
[here](https://github.com/llvm/llvm-project/pull/171610#discussion_r2687382481).
Extracted `get_runtimes_target_libdir_common` from compiler-rt as
requested
[here](https://github.com/llvm/llvm-project/pull/171610#discussion_r2689565634).
Added TODO comments to all runtimes as requested
[here](https://github.com/llvm/llvm-project/pull/171610#issuecomment-3789598635).
Session::tryCreateService will try to create an instance of ServiceT by
forwarding the given arguments to the ServiceT::Create method, which
must return an Expected<std::unique_ptr<ServiceT>>.
This enables one-line construction and registration of Services with
fallible constructors (which are expected to be common).
This argument should be used by ControllerAccess implementations to pass
bootstrap information (process triple, page size, initial symbols and
values) to the controller.
A Session begins in the Start state. In this state no calls will be
received from the controller (since none is attached yet). This provides
clients with an opportunity to configure the Session before attaching a
ControllerAccess object with the `attach` method.
The first call to the `attach` method will register a ControllerAccess
object with the Session, and the ControllerAccess's connect method will
be called to establish a connection with the controller.
If ControllerAccess::connect fails it must call
ControllerAccess::notifyDisconnected, at which point the Session will
proceed to the Detached state.
If ControllerAccess::connect succeeds (i.e. returns without calling
notifyDisconnected) then the Session moves to the Attached state, and
calls can be made in both directions between the executor and
controller.
If at any point Session::detach is called, or if the ControllerAccess
object calls notifyDisconnected, then the Session will release its
reference to the ControllerAccess object, and all Services will have
their onDetach callbacks run.
In the Detached state no calls can be made between the controller and
executor, but existing JIT'd code may continue running. Attempts to call
the controller will result in an error.
When the shutdown method is called the Session will begin shutting down.
The Session will first be detached (if it has not been already), and
then all Services will have their onShutdown methods called.
The `addService`, `attach`, `detach`, `shutdown`, and `callController`
methods can be called from any thread. Any Service added is guaranteed
to have its onDetach and onShutdown callbacks run in order, either when
those events occur or immediately upon being added (if added after the
respective events).
The ShutdownRequested flag indicates to Services whether a shutdown
operation is already pending. Services may use this information to
optimize their book-keeping: either preparing for a (potentially
lengthy) detached state, or for an upcoming shutdown.
Session does not call onDetached yet: That (including setting the
ShutdownRequested argument) will happen in a follow-up patch.
TaskGroup provides a mechanism for tracking execution of multiple
concurrent tasks and receiving notification when all tasks have
completed. This is useful for coordinating asynchronous operations in
the ORC runtime.
TaskGroup::Token is an RAII handle representing participation in a
group. The group cannot complete while any valid (non-default) Token
exists.
TaskGroup::addOnComplete registers callbacks to run when the group
closes and all tokens are released. (Callbacks registered after
completion run immediately).
TalkGroup::close seals the group: no new tokens can be acquired after
close is called.
All methods may be called concurrently from multiple threads.
SimpleNativeMemoryMap now captures a reference to the Session that it
was constructed for. This is used to fix some outstanding TODOs: using
the real page size for the process, and reporting errors that were
previously discarded.
Add named constructors to SimpleNativeMemoryMap to publish
SimpleNativeMemoryMap's controller interface when an instance is
constructed.
This supports correct setup by construction, since API clients can't
forget to publish the interface that the controller will need to
interact with the SimpleNativeMemoryMap object.
BootstrapInfo holds information needed to bootstrap the ExecutionSession
in the controller. Future patches will update ControllerAccess to send
the bootstrap information at controller-connection time.
BootstrapInfo includes information about the executor process (via
Session::processInfo), an initial set of symbols (replacing
Session::controllerInterface()), and a simple key/value store.
…ition.
Renames the SimpleSymbolTable addSymbolsUnique method to addUnique. The
new class name (from c727cd9a4b2) already implies that we're adding
symbols.
This commit also relaxes the error condition for addUnique: Rather than
rejecting any duplicate symbols, it only rejects symbols that were
previously added with a different address. This makes it safe to add the
same symbol(s) multiple time, as long as all definitions point to the
same address. The intent of this is to allow ORC runtime components to
unconditionally add their interfaces to symbols, even if that interface
might have been added previously.
This provides clean separation between the ORC runtime code that
implements runtime functionality and the wrapper functions that permit
this code to be called from the controller via the
ExecutorProcessControl API.
Separating the controller interface from the implementation functions
should allow clients to introduce alternative serialization schemes if
they want (e.g. JSON).
In particular, this commit adds a new orc-rt/include/orc-rt/sps-ci
directory and moves SimpleNativeMemoryMap SPS controller interface into
a new header in that directory. This commit also splits the
implementation and testing of the SPS controller interface for
SimpleNativeMemoryMap into separate files.
ControllerInterface holds the set of named symbols that the ORC runtime
exposes to the controller for bootstrapping the ExecutionSession.
Insertion is checked: duplicate symbols are rejected with an error.
Session is updated to own a ControllerInterface instance, pre-populated
with an orc_rt_SessionInstance entry pointing to the Session object.
The Controller Interface is the extended set of symbols (mostly wrapper
functions) that the controller can call prior to loading any JIT'd code.
It is expected that it will be used to inspect the process and create /
configure services to enable JITing.
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.
