MayaFlux 1.0.0
Digital-First Multimedia Processing Framework
Loading...
Searching...
No Matches
Session.hpp
Go to the documentation of this file.
1#pragma once
2
3#include "Lila/Address.hpp"
4#include "Lila/EvalReport.hpp"
5
6#include <expected>
7
9struct AcquireFailure;
10}
11
12namespace MayaFlux::Host {
13
14/**
15 * @brief Why a Host call was refused, with every path that was checked.
16 */
17struct Failure {
18 std::string message;
19 std::vector<std::filesystem::path> tried;
20};
21
22/**
23 * @brief Result of a Host call.
24 */
25template <typename T = void>
26using Result = std::expected<T, Failure>;
27
28/**
29 * @brief Start a Lila interpreter and a server inside this process.
30 *
31 * Applies everything staged before this call: include paths and flags,
32 * then libraries, then evaluations, in the order they were staged. The
33 * listener starts only after those succeed. The attempt consumes the
34 * staged items whether or not it succeeds. If any staged library or evaluation
35 * fails, or the server cannot listen, the session is torn down and the failure
36 * is returned.
37 *
38 * Only one session is permitted per process. Staging calls made on other
39 * threads while the start is in progress are refused, not queued.
40 *
41 * @param where A UnixAddress by default: a socket only the owner can use, at
42 * the default path in the user's runtime directory. A TcpAddress is an
43 * explicit choice.
44 * @return Success, or the reason the session did not start.
45 */
46MAYAFLUX_HOST_API Result<void> start_session(const Lila::Address& where = Lila::UnixAddress {});
47
48/**
49 * @brief Stop the running session.
50 *
51 * Function pointers obtained through the session become invalid. Libraries
52 * loaded through Host are forgotten, so a later session loads them again.
53 *
54 * @param clear_persistent_store If true, also empties the persistent store.
55 */
56MAYAFLUX_HOST_API void stop_session(bool clear_persistent_store = false);
57
58/**
59 * @brief True if a session is running in this process.
60 */
61[[nodiscard]] MAYAFLUX_HOST_API bool session_active();
62
63/**
64 * @brief Where the running session listens, with anything resolved at start filled in.
65 * @return The address, or nothing if no session is running.
66 */
67[[nodiscard]] MAYAFLUX_HOST_API std::optional<Lila::Address> session_address();
68
69/**
70 * @brief Evaluate a code snippet.
71 *
72 * Before start_session the snippet is staged and evaluated at start.
73 *
74 * @param code C++ code to evaluate.
75 * @return Success, or the interpreter's error text.
76 */
77MAYAFLUX_HOST_API Result<void> eval(const std::string& code);
78
79/**
80 * @brief What one evaluation did, as Lila reports it.
81 *
82 * The views in the report are valid only during the observer call.
83 */
85using EvalOrigin = Lila::EvalOrigin;
86
87using EvalObserver = std::function<void(const EvalReport&)>;
88
89/**
90 * @brief Identifies an observer for remove_eval_observer. Never zero.
91 */
92using ObserverId = uint64_t;
93
94/**
95 * @brief Observe every evaluation in the session, whoever sent it.
96 *
97 * The observer receives a report for each block this process evaluates, including
98 * the blocks staged before start_session, and for each block a client sends,
99 * whether it succeeded or failed. EvalOrigin tells them apart. It runs on the
100 * thread that evaluated, which for a client is the listener's thread, so it must
101 * not block, and an exception that escapes it is logged and dropped. Observers can
102 * be added before the session starts and outlive it.
103 *
104 * @param observer Called with each report.
105 * @return An id for remove_eval_observer.
106 */
107MAYAFLUX_HOST_API ObserverId on_eval(EvalObserver observer);
108
109/**
110 * @brief Stop observing. An unknown id is ignored. A call already running on another
111 * thread may still be finishing when this returns.
112 */
113MAYAFLUX_HOST_API void remove_eval_observer(ObserverId id);
114
115/**
116 * @brief Evaluate a source file by including it.
117 *
118 * The file is checked at call time. Before start_session the include is
119 * staged and evaluated at start.
120 *
121 * @param path Path to an existing regular file, absolute or relative to the working directory.
122 * @return Success, or the reason the file was refused or failed to evaluate.
123 */
124MAYAFLUX_HOST_API Result<void> eval_file(const std::filesystem::path& path);
125
126/**
127 * @brief Address of a symbol defined in the running session.
128 *
129 * @param name Symbol name.
130 * @return The address, or the reason there is none.
131 */
132MAYAFLUX_HOST_API Result<void*> symbol_address(const std::string& name);
133
134namespace detail {
135
136 enum class Stage : uint8_t {
141 };
142
143 /**
144 * @brief Apply an item to the running session, or stage it until start_session.
145 *
146 * Include paths and flags cannot change a session that has started and
147 * are refused then. Libraries are loaded once per path.
148 */
149 MAYAFLUX_HOST_API Result<void> apply_or_stage(Stage stage, std::string value);
150
151 MAYAFLUX_HOST_API Failure to_failure(const Platform::AcquireFailure& failure);
152
153}
154
155} // namespace MayaFlux::Host
Failure to_failure(const Platform::AcquireFailure &failure)
Definition Session.cpp:165
Result< void > apply_or_stage(Stage stage, std::string value)
Apply an item to the running session, or stage it until start_session.
Definition Session.cpp:129
Lila::EvalOrigin EvalOrigin
Definition Session.hpp:85
std::expected< T, Failure > Result
Result of a Host call.
Definition Session.hpp:26
std::function< void(const EvalReport &)> EvalObserver
Definition Session.hpp:87
Result< void * > symbol_address(const std::string &name)
Address of a symbol defined in the running session.
Definition Session.cpp:379
Result< void > eval(const std::string &code)
Evaluate a code snippet.
Definition Session.cpp:342
std::optional< Lila::Address > session_address()
Where the running session listens, with anything resolved at start filled in.
Definition Session.cpp:336
uint64_t ObserverId
Identifies an observer for remove_eval_observer.
Definition Session.hpp:92
void remove_eval_observer(ObserverId id)
Stop observing.
Definition Session.cpp:357
bool session_active()
True if a session is running in this process.
Definition Session.cpp:330
Result< void > start_session(const Lila::Address &where)
Start a Lila interpreter and a server inside this process.
Definition Session.cpp:213
Lila::EvalReport EvalReport
What one evaluation did, as Lila reports it.
Definition Session.hpp:84
ObserverId on_eval(EvalObserver observer)
Observe every evaluation in the session, whoever sent it.
Definition Session.cpp:347
Result< void > eval_file(const std::filesystem::path &path)
Evaluate a source file by including it.
Definition Session.cpp:364
void stop_session(bool clear_persistent_store)
Stop the running session.
Definition Session.cpp:298
What one evaluation did.
A Unix domain socket: a socket file that only its owner can use.
Definition Address.hpp:25
std::vector< std::filesystem::path > tried
Definition Session.hpp:19
Why a Host call was refused, with every path that was checked.
Definition Session.hpp:17
Why an acquisition request was refused, with every path that was checked.