StormByte 3.0.0
C++26 foundation of the StormByte suite
Loading...
Searching...
No Matches
function.hxx
Go to the documentation of this file.
1/*
2 * Copyright (C) 2024-2026 David C. Manuelda (StormBytePP)
3 *
4 * This is the base for StormByte Suite libraries.
5 *
6 * StormByte original source is dual-licensed:
7 *
8 * 1. GNU Lesser General Public License v3.0 (or later)
9 * You may redistribute and/or modify this file under the terms of the
10 * GNU Lesser General Public License as published by the Free Software
11 * Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * 2. Commercial license
15 * Alternatively, this file may be used under the terms of a commercial
16 * license agreement with the copyright holder
17 * (David C. Manuelda <StormByte@gmail.com>).
18 *
19 * Both licenses apply only to original StormByte source in this repository.
20 * They do not cover other StormByte modules or any third-party material
21 * shipped with this repository (including everything under thirdparty/),
22 * which remains under its own license.
23 *
24 * Neither license grants any patent rights. Any patent licenses required
25 * to use this software or third-party components must be obtained separately
26 * from the patent holders.
27 *
28 * StormByte is distributed in the hope that it will be useful,
29 * but WITHOUT ANY WARRANTY; without even the implied warranty of
30 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 * GNU Lesser General Public License for more details.
32 *
33 * You should have received a copy of the GNU Lesser General Public License
34 * version 3 along with StormByte. If not, see
35 * <https://www.gnu.org/licenses/lgpl-3.0.html>.
36 *
37 * SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-StormByte-Commercial
38 */
39
40#pragma once
41
46
47#include <type_traits>
48#include <utility>
49
54namespace StormByte {
59 namespace Safe {
64 namespace Detail {
70 template<typename T>
73 (!std::is_reference_v<T> || (std::is_lvalue_reference_v<T> && std::is_const_v<std::remove_reference_t<T>>));
74 }
75
97 template<typename Signature>
98 class Function;
99
104 template<typename... Args>
105 requires (Detail::SafeCallbackArgument<Args> && ...)
106 class STORMBYTE_PUBLIC_TYPE Function<void(Args...)> final {
107 public:
111 using Invoke = Status (*)(void*, Args...);
112
116 using Clone = void* (*)(const void*) noexcept;
117
121 using Release = void (*)(void*) noexcept;
122
132 Function(void* context, Invoke invoke, Clone clone, Release release):
133 m_owner(nullptr, nullptr, nullptr), m_invoke(invoke) {
134 if (!context || !invoke || !clone || !release)
135 throw StormByte::Exception("Safe function requires context, invoke, clone and release");
136 m_owner = Detail::Owner(context, clone, release);
137 }
138
144 Function(const Function& other) = default;
145
152 Function& operator=(const Function& other) = default;
153
158 Function(Function&& other) noexcept:
159 m_owner(std::move(other.m_owner)), m_invoke(std::exchange(other.m_invoke, nullptr)) {}
160
166 Function& operator=(Function&& other) noexcept {
167 if (this != &other) {
168 m_owner = std::move(other.m_owner);
169 m_invoke = std::exchange(other.m_invoke, nullptr);
170 }
171 return *this;
172 }
173
177 ~Function() noexcept = default;
178
183 bool HasValue() const noexcept {
184 return m_owner.Get() != nullptr;
185 }
186
194 Status Call(Args... args) const {
195 if (!HasValue())
196 return Status::Missing;
197 try {
198 return m_invoke(m_owner.Get(), std::forward<Args>(args)...);
199 } catch (const StormByte::Exception&) {
200 throw;
201 } catch (...) {
202 return Status::Failure;
203 }
204 }
205
206 private:
207 Detail::Owner m_owner;
208 Invoke m_invoke;
209 };
210
220 template<typename Return, typename... Args>
221 requires (!std::is_void_v<Return>) && (!std::is_reference_v<Return>) &&
222 Detail::SafeCallbackArgument<Return> && (Detail::SafeCallbackArgument<Args> && ...) &&
224 requires(Return& output, Return&& result) { { output = std::move(result) } noexcept; }
225 class STORMBYTE_PUBLIC_TYPE Function<Return(Args...)> final {
226 public:
230 using Invoke = Status (*)(void*, Return*, Args...);
234 using Clone = void* (*)(const void*) noexcept;
238 using Release = void (*)(void*) noexcept;
239
248 Function(void* context, Invoke invoke, Clone clone, Release release):
249 m_owner(nullptr, nullptr, nullptr), m_invoke(invoke) {
250 if (!context || !invoke || !clone || !release)
251 throw StormByte::Exception("Safe function requires context, invoke, clone and release");
252 m_owner = Detail::Owner(context, clone, release);
253 }
254
260 Function(const Function& other) = default;
267 Function& operator=(const Function& other) = default;
272 Function(Function&& other) noexcept:
273 m_owner(std::move(other.m_owner)), m_invoke(std::exchange(other.m_invoke, nullptr)) {}
274
279 Function& operator=(Function&& other) noexcept {
280 if (this != &other) {
281 m_owner = std::move(other.m_owner);
282 m_invoke = std::exchange(other.m_invoke, nullptr);
283 }
284 return *this;
285 }
286
289 ~Function() noexcept = default;
290
295 bool HasValue() const noexcept {
296 return m_owner.Get() != nullptr;
297 }
298
306 Status Call(Return& output, Args... args) const {
307 if (!HasValue())
308 return Status::Missing;
309 try {
310 Return result(output);
311 const Status status = m_invoke(m_owner.Get(), &result, std::forward<Args>(args)...);
312 if (status == Status::Success)
313 output = std::move(result);
314 return status;
315 } catch (const StormByte::Exception&) {
316 throw;
317 } catch (...) {
318 return Status::Failure;
319 }
320 }
321
322 private:
323 Detail::Owner m_owner;
324 Invoke m_invoke;
325 };
326 }
327}
328
329
334namespace StormByte {
339 namespace Type {
344 template<typename... Args>
345 requires (Safe::Detail::SafeCallbackArgument<Args> && ...) &&
347 struct IsMaybeSafe<Safe::Function<void(Args...)>>: std::true_type {};
348
354 template<typename Return, typename... Args>
355 requires (!std::is_void_v<Return>) && Safe::Detail::SafeCallbackArgument<Return> &&
359 requires(Return& output, Return&& value) { { output = std::move(value) } noexcept; }
360 struct IsMaybeSafe<Safe::Function<Return(Args...)>>: std::true_type {};
361 }
362}
Base exception type for the suite.
Definition exception.hxx:67
Opaque unique state and creator-module lifetime callbacks.
Definition owner.hxx:81
bool HasValue() const noexcept
Whether this callback still owns a context.
Definition function.hxx:295
Status Call(Return &output, Args... args) const
Invoke and write a successful result to caller-owned storage.
Definition function.hxx:306
Function & operator=(Function &&other) noexcept
Release current context and transfer.
Definition function.hxx:279
void *(*)(const void *) noexcept Clone
Provider context clone function pointer; null reports failure.
Definition function.hxx:234
Function & operator=(const Function &other)=default
Deep-copy provider context with the strong guarantee.
void(*)(void *) noexcept Release
Provider context destruction function pointer.
Definition function.hxx:238
Function(const Function &other)=default
Deep-copy provider context.
~Function() noexcept=default
Release context through its provider callback.
Function(Function &&other) noexcept
Transfer callback context.
Definition function.hxx:272
Status(*)(void *, Return *, Args...) Invoke
Provider invocation function pointer.
Definition function.hxx:230
Function(void *context, Invoke invoke, Clone clone, Release release)
Adopt provider-owned callback context.
Definition function.hxx:248
Function(void *context, Invoke invoke, Clone clone, Release release)
Adopt provider-owned callback context.
Definition function.hxx:132
void(*)(void *) noexcept Release
Provider context destruction function pointer.
Definition function.hxx:121
Status(*)(void *, Args...) Invoke
Provider invocation function pointer.
Definition function.hxx:111
~Function() noexcept=default
Release context through its provider callback.
Function & operator=(Function &&other) noexcept
Release the current context and transfer another callback.
Definition function.hxx:166
Function & operator=(const Function &other)=default
Deep-copy provider context with the strong guarantee.
bool HasValue() const noexcept
Whether this callback still owns a context.
Definition function.hxx:183
void *(*)(const void *) noexcept Clone
Provider context clone function; null reports failure.
Definition function.hxx:116
Function(Function &&other) noexcept
Transfer callback context.
Definition function.hxx:158
Status Call(Args... args) const
Invoke the provider callback.
Definition function.hxx:194
Function(const Function &other)=default
Deep-copy provider-owned context.
Copyable, creator-context callback with a typed signature.
Definition function.hxx:98
Callback arguments admitted across a DLL boundary.
Definition function.hxx:71
Type that can actually be copy-constructed.
Definition object_semantics.hxx:189
Recognized Safe component after stripping cv and references.
Definition safe.hxx:311
Value permitted in opaque Safe collections.
Definition safe.hxx:409
Private helpers.
Owned values that cross a DLL without the caller's CRT.
Status
Result of a collection operation; exceptions never leave its owner callback.
Definition owner.hxx:59
@ Missing
Index or key is absent.
Definition owner.hxx:61
@ Success
Operation completed.
Definition owner.hxx:60
@ Failure
Allocation, copying or comparison failed; no exception crosses the callback.
Definition owner.hxx:62
Named concepts and small type utilities used across the suite.
Root namespace of the StormByte suite.
Recognizes types whose DLL-boundary safety depends on documented provider requirements.
Definition safe.hxx:262
#define STORMBYTE_PUBLIC_TYPE
Definition visibility.h:57