Sane C++ Libraries
C++ Platform Abstraction Libraries
Loading...
Searching...
No Matches
Async.h
1// Copyright (c) Stefano Cristiano
2// SPDX-License-Identifier: MIT
3#pragma once
4
5#include "../Async/Internal/IntrusiveDoubleLinkedList.h"
6#include "../File/File.h"
7#include "../FileSystem/FileSystem.h"
8#include "../Foundation/Function.h"
9#include "../Foundation/OpaqueObject.h"
10#include "../Socket/Socket.h"
11#include "../Threading/Atomic.h"
12#include "../Threading/ThreadPool.h"
13#include "../Time/Time.h"
14
15namespace SC
16{
17struct ThreadPool;
18struct ThreadPoolTask;
19struct EventObject;
20} // namespace SC
45
48namespace SC
49{
50struct AsyncEventLoop;
51struct AsyncResult;
52struct AsyncSequence;
53struct AsyncTaskSequence;
54
55namespace detail
56{
57struct AsyncWinOverlapped;
58struct AsyncWinOverlappedDefinition
59{
60 static constexpr int Windows = sizeof(void*) * 4 + sizeof(uint64_t);
61 static constexpr size_t Alignment = alignof(void*);
62
63 using Object = AsyncWinOverlapped;
64};
65using WinOverlappedOpaque = OpaqueObject<AsyncWinOverlappedDefinition>;
66
67struct AsyncWinWaitDefinition
68{
69 using Handle = FileDescriptor::Handle; // fd
70 static constexpr Handle Invalid = FileDescriptor::Invalid; // invalid fd
71
72 static Result releaseHandle(Handle& waitHandle);
73};
74struct WinWaitHandle : public UniqueHandle<AsyncWinWaitDefinition>
75{
76};
77} // namespace detail
78
118{
119 AsyncRequest* next = nullptr;
120 AsyncRequest* prev = nullptr;
121
122 void setDebugName(const char* newDebugName);
123
125 void executeOn(AsyncSequence& sequence);
126
131
134
153
156 AsyncRequest(Type type) : state(State::Free), type(type), flags(0), unused(0), userFlags(0) {}
157
164 Result stop(AsyncEventLoop& eventLoop, Function<void(AsyncResult&)>* afterStopped = nullptr);
165
167 [[nodiscard]] bool isFree() const;
168
170 [[nodiscard]] bool isCancelling() const;
171
173 [[nodiscard]] bool isActive() const;
174
176 [[nodiscard]] Type getType() const { return type; }
177
180
182 void setUserFlags(uint16_t externalFlags) { userFlags = externalFlags; }
183
185 uint16_t getUserFlags() const { return userFlags; }
186
188 [[nodiscard]] Function<void(AsyncResult&)>* getCloseCallback() { return closeCallback; }
189
190 [[nodiscard]] const Function<void(AsyncResult&)>* getCloseCallback() const { return closeCallback; }
191
192 protected:
193 Result checkState();
194
195 void queueSubmission(AsyncEventLoop& eventLoop);
196
197 AsyncSequence* sequence = nullptr;
198
199 AsyncTaskSequence* getTask();
200
201 private:
202 Function<void(AsyncResult&)>* closeCallback = nullptr;
203
204 friend struct AsyncEventLoop;
205 friend struct AsyncResult;
206
207 void markAsFree();
208
209 [[nodiscard]] static const char* TypeToString(Type type);
210 enum class State : uint8_t
211 {
212 Free, // not in any queue, this can be started with an async.start(...)
213 Setup, // when in submission queue waiting to be setup (after an async.start(...))
214 Submitting, // when in submission queue waiting to be activated or re-activated
215 Active, // when monitored by OS syscall or in activeLoopWakeUps / activeTimeouts queues
216 Reactivate, // when flagged for reactivation inside the callback (after a result.reactivateRequest(true))
217 Cancelling, // when in cancellation queue waiting for a cancelAsync (on active async)
218 };
219
220#if SC_ASYNC_ENABLE_LOG
221 const char* debugName = "None";
222#endif
223 State state; // 1 byte
224 Type type; // 1 byte
225 int16_t flags; // 2 bytes
226
227 uint16_t unused; // 2 bytes
228 uint16_t userFlags; // 2 bytes
229};
230
236{
237 AsyncSequence* next = nullptr;
238 AsyncSequence* prev = nullptr;
239
242 private:
243 friend struct AsyncEventLoop;
244 bool runningAsync = false; // true if an async from this sequence is being run
245 bool tracked = false;
246
247 IntrusiveDoubleLinkedList<AsyncRequest> submissions;
248};
249
252{
253};
254
258{
260 AsyncResult(AsyncEventLoop& eventLoop, AsyncRequest& request, SC::Result& res, bool* hasBeenReactivated = nullptr)
261 : eventLoop(eventLoop), async(request), hasBeenReactivated(hasBeenReactivated), returnCode(res)
262 {}
263
266 void reactivateRequest(bool shouldBeReactivated);
267
269 [[nodiscard]] const SC::Result& isValid() const { return returnCode; }
270
271 AsyncEventLoop& eventLoop;
272 AsyncRequest& async;
273
274 protected:
275 friend struct AsyncEventLoop;
276
277 bool shouldCallCallback = true;
278 bool* hasBeenReactivated = nullptr;
279
280 SC::Result& returnCode;
281};
282
286template <typename T, typename C>
288{
289 T& getAsync() { return static_cast<T&>(AsyncResult::async); }
290 const T& getAsync() const { return static_cast<const T&>(AsyncResult::async); }
291
293
294 C completionData;
295 int32_t eventIndex = 0;
296};
297
325
361
367{
369
371 {
372 int exitStatus;
373 };
374
375 struct Result : public AsyncResultOf<AsyncProcessExit, CompletionData>
376 {
377 using AsyncResultOf<AsyncProcessExit, CompletionData>::AsyncResultOf;
378
379 SC::Result get(int& status)
380 {
381 status = completionData.exitStatus;
382 return returnCode;
383 }
384 };
386
390 SC::Result start(AsyncEventLoop& eventLoop, FileDescriptor::Handle process);
391
393
394 private:
395 friend struct AsyncEventLoop;
396 SC::Result validate(AsyncEventLoop&);
397
398 FileDescriptor::Handle handle = FileDescriptor::Invalid;
399#if SC_PLATFORM_WINDOWS
401 detail::WinWaitHandle waitHandle;
402 AsyncEventLoop* eventLoop = nullptr;
403#elif SC_PLATFORM_LINUX
404 FileDescriptor pidFd;
405#endif
406};
407
408struct AsyncSocketAccept;
409namespace detail
410{
413struct AsyncSocketAcceptData
414{
415#if SC_PLATFORM_WINDOWS
416 void (*pAcceptEx)() = nullptr;
418 SocketDescriptor clientSocket;
419 uint8_t acceptBuffer[288] = {0};
420#elif SC_PLATFORM_LINUX
421 AlignedStorage<28> sockAddrHandle;
422 uint32_t sockAddrLen;
423#endif
424};
425
427struct AsyncSocketAcceptBase : public AsyncRequest
428{
429 AsyncSocketAcceptBase() : AsyncRequest(Type::SocketAccept) {}
430
431 struct CompletionData : public AsyncCompletionData
432 {
433 SocketDescriptor acceptedClient;
434 };
435
436 struct Result : public AsyncResultOf<AsyncSocketAccept, CompletionData>
437 {
438 using AsyncResultOf<AsyncSocketAccept, CompletionData>::AsyncResultOf;
439
440 SC::Result moveTo(SocketDescriptor& client)
441 {
442 SC_TRY(returnCode);
443 return client.assign(move(completionData.acceptedClient));
444 }
445 };
447
449 SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& socketDescriptor, AsyncSocketAcceptData& data);
450 SC::Result validate(AsyncEventLoop&);
451
452 Function<void(Result&)> callback;
453 SocketDescriptor::Handle handle = SocketDescriptor::Invalid;
455 AsyncSocketAcceptData* acceptData = nullptr;
456};
457
458} // namespace detail
459
469struct AsyncSocketAccept : public detail::AsyncSocketAcceptBase
470{
471 AsyncSocketAccept() { AsyncSocketAcceptBase::acceptData = &data; }
472 using AsyncSocketAcceptBase::start;
473
475 SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& socketDescriptor);
476
477 private:
478 detail::AsyncSocketAcceptData data;
479};
480
490{
492
496
498 SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, SocketIPAddress address);
499
501
502 SocketDescriptor::Handle handle = SocketDescriptor::Invalid;
503 SocketIPAddress ipAddress;
504
505 private:
506 friend struct AsyncEventLoop;
507 SC::Result validate(AsyncEventLoop&);
508
509#if SC_PLATFORM_WINDOWS
510 void (*pConnectEx)() = nullptr;
512#endif
513};
514
524{
527 {
528 size_t numBytes = 0;
529 };
532
535
538
540
541 SocketDescriptor::Handle handle = SocketDescriptor::Invalid;
542
545 bool singleBuffer = true;
546
547 protected:
548 AsyncSocketSend(Type type) : AsyncRequest(type) {}
549 friend struct AsyncEventLoop;
550 SC::Result validate(AsyncEventLoop&);
551
552 size_t totalBytesWritten = 0;
553#if SC_PLATFORM_WINDOWS
555#endif
556};
557
568{
570
571 SocketIPAddress address;
572
573 SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, SocketIPAddress ipAddress,
574 Span<const char> data);
575
576 SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, SocketIPAddress ipAddress,
577 Span<Span<const char>> data);
578
579 private:
581 friend struct AsyncEventLoop;
582 SC::Result validate(AsyncEventLoop&);
583#if SC_PLATFORM_LINUX
584 AlignedStorage<56> typeErasedMsgHdr;
585#endif
586};
587
600{
602
604 {
605 size_t numBytes = 0;
606 bool disconnected = false;
607 };
608
609 struct Result : public AsyncResultOf<AsyncSocketReceive, CompletionData>
610 {
611 using AsyncResultOf<AsyncSocketReceive, CompletionData>::AsyncResultOf;
612
617 {
618 SC_TRY(getAsync().buffer.sliceStartLength(0, completionData.numBytes, outData));
619 return returnCode;
620 }
621
622 SocketIPAddress getSourceAddress() const;
623 };
625
627 SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, Span<char> data);
628
630
632 SocketDescriptor::Handle handle = SocketDescriptor::Invalid;
633
634 protected:
636 friend struct AsyncEventLoop;
637 SC::Result validate(AsyncEventLoop&);
638#if SC_PLATFORM_WINDOWS
640#endif
641};
642
653{
656
657 private:
658 SocketIPAddress address;
659 friend struct AsyncSocketReceive;
660 friend struct AsyncEventLoop;
661#if SC_PLATFORM_LINUX
662 AlignedStorage<56> typeErasedMsgHdr;
663#endif
664};
665
688{
689 AsyncFileRead() : AsyncRequest(Type::FileRead) { handle = FileDescriptor::Invalid; }
690
692 {
693 size_t numBytes = 0;
694 bool endOfFile = false;
695 };
696
697 struct Result : public AsyncResultOf<AsyncFileRead, CompletionData>
698 {
699 using AsyncResultOf<AsyncFileRead, CompletionData>::AsyncResultOf;
700
701 SC::Result get(Span<char>& data)
702 {
703 SC_TRY(getAsync().buffer.sliceStartLength(0, completionData.numBytes, data));
704 return returnCode;
705 }
706 };
708
709 Function<void(Result&)> callback;
711 FileDescriptor::Handle handle;
713
715 uint64_t getOffset() const { return offset; }
716
719 void setOffset(uint64_t fileOffset)
720 {
721 useOffset = true;
722 offset = fileOffset;
723 }
724
725 private:
726 friend struct AsyncEventLoop;
727 SC::Result validate(AsyncEventLoop&);
728 bool useOffset = false;
729 uint64_t offset = 0;
730#if SC_PLATFORM_WINDOWS
731 uint64_t readCursor = 0;
733#endif
734};
735
754{
755 AsyncFileWrite() : AsyncRequest(Type::FileWrite) { handle = FileDescriptor::Invalid; }
756
758 {
759 size_t numBytes = 0;
760 };
761
762 struct Result : public AsyncResultOf<AsyncFileWrite, CompletionData>
763 {
764 using AsyncResultOf<AsyncFileWrite, CompletionData>::AsyncResultOf;
765
766 SC::Result get(size_t& writtenSizeInBytes)
767 {
768 writtenSizeInBytes = completionData.numBytes;
769 return returnCode;
770 }
771 };
772
774
777
780
782
783 FileDescriptor::Handle handle;
785
788 bool singleBuffer = true;
789
791 uint64_t getOffset() const { return offset; }
792
795 void setOffset(uint64_t fileOffset)
796 {
797 useOffset = true;
798 offset = fileOffset;
799 }
800
801 private:
802 friend struct AsyncEventLoop;
803 SC::Result validate(AsyncEventLoop&);
804
805#if SC_PLATFORM_WINDOWS
806#else
807 bool isWatchable = false;
808#endif
809 bool useOffset = false;
810 uint64_t offset = 0xffffffffffffffff;
811
812 size_t totalBytesWritten = 0;
813#if SC_PLATFORM_WINDOWS
815#endif
816};
817
823{
825
828
830 SC::Result start(AsyncEventLoop& eventLoop, FileDescriptor::Handle fileDescriptor);
831
832#if SC_PLATFORM_WINDOWS
833 [[nodiscard]] auto& getOverlappedOpaque() { return overlapped; }
834#endif
835
836 Function<void(Result&)> callback;
837
838 private:
839 friend struct AsyncEventLoop;
840 SC::Result validate(AsyncEventLoop&);
841
842 FileDescriptor::Handle handle = FileDescriptor::Invalid;
843#if SC_PLATFORM_WINDOWS
845#endif
846};
847
848// forward declared because it must be defined after AsyncTaskSequence
849struct AsyncLoopWork;
850struct AsyncFileSystemOperation;
851
853{
854 FileDescriptor::Handle handle = FileDescriptor::Invalid; // for open
855
856 int code = 0; // for open/close
857 size_t numBytes = 0; // for read
858};
859
860namespace detail
861{
862// A simple hand-made variant of all completion types
863struct AsyncCompletionVariant
864{
865 AsyncCompletionVariant() {}
866 ~AsyncCompletionVariant() { destroy(); }
867
868 AsyncCompletionVariant(const AsyncCompletionVariant&) = delete;
869 AsyncCompletionVariant(AsyncCompletionVariant&&) = delete;
870 AsyncCompletionVariant& operator=(const AsyncCompletionVariant&) = delete;
871 AsyncCompletionVariant& operator=(AsyncCompletionVariant&&) = delete;
872
873 bool inited = false;
874
876 union
877 {
878 AsyncCompletionData completionDataLoopWork; // Defined after AsyncCompletionVariant / AsyncTaskSequence
879 AsyncLoopTimeout::CompletionData completionDataLoopTimeout;
880 AsyncLoopWakeUp::CompletionData completionDataLoopWakeUp;
881 AsyncProcessExit::CompletionData completionDataProcessExit;
882 AsyncSocketAccept::CompletionData completionDataSocketAccept;
883 AsyncSocketConnect::CompletionData completionDataSocketConnect;
884 AsyncSocketSend::CompletionData completionDataSocketSend;
885 AsyncSocketSendTo::CompletionData completionDataSocketSendTo;
886 AsyncSocketReceive::CompletionData completionDataSocketReceive;
887 AsyncSocketReceiveFrom::CompletionData completionDataSocketReceiveFrom;
888 AsyncFileRead::CompletionData completionDataFileRead;
889 AsyncFileWrite::CompletionData completionDataFileWrite;
890 AsyncFilePoll::CompletionData completionDataFilePoll;
891
892 AsyncFileSystemOperationCompletionData completionDataFileSystemOperation;
893 };
894
895 auto& getCompletion(AsyncLoopWork&) { return completionDataLoopWork; }
896 auto& getCompletion(AsyncLoopTimeout&) { return completionDataLoopTimeout; }
897 auto& getCompletion(AsyncLoopWakeUp&) { return completionDataLoopWakeUp; }
898 auto& getCompletion(AsyncProcessExit&) { return completionDataProcessExit; }
899 auto& getCompletion(AsyncSocketAccept&) { return completionDataSocketAccept; }
900 auto& getCompletion(AsyncSocketConnect&) { return completionDataSocketConnect; }
901 auto& getCompletion(AsyncSocketSend&) { return completionDataSocketSend; }
902 auto& getCompletion(AsyncSocketReceive&) { return completionDataSocketReceive; }
903 auto& getCompletion(AsyncFileRead&) { return completionDataFileRead; }
904 auto& getCompletion(AsyncFileWrite&) { return completionDataFileWrite; }
905 auto& getCompletion(AsyncFilePoll&) { return completionDataFilePoll; }
906 auto& getCompletion(AsyncFileSystemOperation&) { return completionDataFileSystemOperation; }
907
908 template <typename T>
909 auto& construct(T& t)
910 {
911 destroy();
912 placementNew(getCompletion(t));
913 inited = true;
914 type = t.getType();
915 return getCompletion(t);
916 }
917 void destroy();
918};
919} // namespace detail
920
925{
926 protected:
927 ThreadPoolTask task;
928 ThreadPool* threadPool = nullptr;
929
930 friend struct AsyncEventLoop;
931 friend struct AsyncRequest;
932
933 detail::AsyncCompletionVariant completion;
934
935 SC::Result returnCode = SC::Result(true);
936};
937
962
997{
999 ~AsyncFileSystemOperation() { destroy(); }
1000#ifdef CopyFile
1001#undef CopyFile
1002#endif
1003#ifdef RemoveDirectory
1004#undef RemoveDirectory
1005#endif
1006 enum class Operation
1007 {
1008 None = 0,
1009 Open,
1010 Close,
1011 Read,
1012 Write,
1013 CopyFile,
1014 CopyDirectory,
1015 Rename,
1016 RemoveDirectory,
1017 RemoveFile,
1018 };
1019
1022
1025
1027
1034
1039 SC::Result close(AsyncEventLoop& eventLoop, FileDescriptor::Handle handle);
1040
1047 SC::Result read(AsyncEventLoop& eventLoop, FileDescriptor::Handle handle, Span<char> buffer, uint64_t offset);
1048
1055 SC::Result write(AsyncEventLoop& eventLoop, FileDescriptor::Handle handle, Span<const char> buffer,
1056 uint64_t offset);
1057
1064 SC::Result copyFile(AsyncEventLoop& eventLoop, StringSpan path, StringSpan destinationPath,
1066
1075
1082
1089
1095
1096 private:
1097 friend struct AsyncEventLoop;
1098 Operation operation = Operation::None;
1099 AsyncLoopWork loopWork;
1100 CompletionData completionData;
1101
1102 void onOperationCompleted(AsyncLoopWork::Result& res);
1103
1104 struct FileDescriptorData
1105 {
1106 FileDescriptor::Handle handle;
1107 };
1108
1109 struct OpenData
1110 {
1111 StringSpan path;
1112 FileOpen mode;
1113 };
1114
1115 struct ReadData
1116 {
1117 FileDescriptor::Handle handle;
1118 Span<char> buffer;
1119 uint64_t offset;
1120 };
1121
1122 struct WriteData
1123 {
1124 FileDescriptor::Handle handle;
1125 Span<const char> buffer;
1126 uint64_t offset;
1127 };
1128
1129 struct CopyFileData
1130 {
1131 StringSpan path;
1132 StringSpan destinationPath;
1133 FileSystemCopyFlags copyFlags;
1134 };
1135
1136 using CopyDirectoryData = CopyFileData;
1137
1138 using CloseData = FileDescriptorData;
1139
1140 struct RenameData
1141 {
1142 StringSpan path;
1143 StringSpan newPath;
1144 };
1145
1146 struct RemoveData
1147 {
1148 StringSpan path;
1149 };
1150
1151 union
1152 {
1153 OpenData openData;
1154 CloseData closeData;
1155 ReadData readData;
1156 WriteData writeData;
1157 CopyFileData copyFileData;
1158 CopyDirectoryData copyDirectoryData;
1159 RenameData renameData;
1160 RemoveData removeData;
1161 };
1162
1163 void destroy();
1164
1165 SC::Result start(AsyncEventLoop& eventLoop, FileDescriptor::Handle fileDescriptor);
1166 SC::Result validate(AsyncEventLoop&);
1167};
1168
1173{
1175
1176 private:
1177 int numberOfEvents = 0;
1178 friend struct AsyncEventLoop;
1179};
1180
1183{
1184 Function<void(AsyncEventLoop&)> beforeBlockingPoll;
1185 Function<void(AsyncEventLoop&)> afterBlockingPoll;
1186};
1187
1195{
1197 struct Options
1198 {
1199 enum class ApiType : uint8_t
1200 {
1201 Automatic = 0,
1204 };
1206
1208 };
1209
1211
1214
1217
1221
1224
1226 [[nodiscard]] bool isInitialized() const;
1227
1234
1245
1252
1258
1278
1285
1289
1292
1295
1298
1301
1304
1307
1310
1313
1315 [[nodiscard]] Time::Monotonic getLoopTime() const;
1316
1318 [[nodiscard]] int getNumberOfActiveRequests() const;
1319
1321 [[nodiscard]] int getNumberOfSubmittedRequests() const;
1322
1326
1329
1332
1334 void enumerateRequests(Function<void(AsyncRequest&)> enumerationCallback);
1335
1339
1341 [[nodiscard]] static bool isExcludedFromActiveCount(const AsyncRequest& async);
1342
1345 [[nodiscard]] static bool tryLoadingLiburing();
1346
1349
1350 struct Internal;
1351
1352 private:
1353 struct InternalDefinition
1354 {
1355 static constexpr int Windows = 520;
1356 static constexpr int Apple = 512;
1357 static constexpr int Linux = 720;
1358 static constexpr int Default = Linux;
1359
1360 static constexpr size_t Alignment = 8;
1361
1362 using Object = Internal;
1363 };
1364
1365 public:
1366 using InternalOpaque = OpaqueObject<InternalDefinition>;
1367
1368 private:
1369 InternalOpaque internalOpaque;
1370 Internal& internal;
1371
1372 friend struct AsyncRequest;
1373 friend struct AsyncFileWrite;
1374 friend struct AsyncFileRead;
1375 friend struct AsyncFileSystemOperation;
1376 friend struct AsyncResult;
1377};
1378
1383{
1385
1389
1392
1400
1406
1407 private:
1408#if SC_COMPILER_MSVC
1409#pragma warning(push)
1410#pragma warning(disable : 4324) // useless warning on 32 bit... (structure was padded due to __declspec(align()))
1411#endif
1412 alignas(uint64_t) uint8_t eventsMemory[8 * 1024]; // 8 Kb of kernel events
1413#if SC_COMPILER_MSVC
1414#pragma warning(pop)
1415#endif
1416
1417 AsyncKernelEvents asyncKernelEvents;
1418 AsyncEventLoop* eventLoop = nullptr;
1419 AsyncLoopWakeUp eventLoopWakeUp;
1420
1421 Thread eventLoopThread;
1422 EventObject eventObjectEnterBlockingMode;
1423 EventObject eventObjectExitBlockingMode;
1424
1425 Atomic<bool> finished = false;
1426 Atomic<bool> needsWakeUp = true;
1427
1428 bool wakeUpHasBeenCalled = false;
1429
1430 Result monitoringLoopThread(Thread& thread);
1431};
1432
1433} // namespace SC
unsigned short uint16_t
Platform independent (2) bytes unsigned int.
Definition PrimitiveTypes.h:37
constexpr T && move(T &value)
Converts an lvalue to an rvalue reference.
Definition Compiler.h:257
unsigned char uint8_t
Platform independent (1) byte unsigned int.
Definition PrimitiveTypes.h:36
unsigned long long uint64_t
Platform independent (8) bytes unsigned int.
Definition PrimitiveTypes.h:42
unsigned int uint32_t
Platform independent (4) bytes unsigned int.
Definition PrimitiveTypes.h:38
short int16_t
Platform independent (2) bytes signed int.
Definition PrimitiveTypes.h:45
int int32_t
Platform independent (4) bytes signed int.
Definition PrimitiveTypes.h:46
#define SC_TRY(expression)
Checks the value of the given expression and if failed, returns this value to caller.
Definition Result.h:48
A buffer of bytes with given alignment.
Definition AlignedStorage.h:29
Empty base struct for all AsyncRequest-derived CompletionData (internal) structs.
Definition Async.h:252
Allow library user to provide callbacks signaling different phases of async event loop cycle.
Definition Async.h:1183
Monitors Async I/O events from a background thread using a blocking kernel function (no CPU usage on ...
Definition Async.h:1383
Function< void(void)> onNewEventsAvailable
Informs to call dispatchCompletions on GUI Event Loop.
Definition Async.h:1384
Result startMonitoring()
Queue all async requests submissions and start monitoring loop events on a background thread.
Result close()
Stop monitoring the AsyncEventLoop, disposing all resources.
Result stopMonitoringAndDispatchCompletions()
Stops monitoring events on the background thread and dispatches callbacks for completed requests.
Result create(AsyncEventLoop &eventLoop)
Create the monitoring thread for an AsyncEventLoop.
Options given to AsyncEventLoop::create.
Definition Async.h:1198
ApiType apiType
Criteria to choose Async IO API.
Definition Async.h:1205
ApiType
Definition Async.h:1200
@ Automatic
Platform specific backend chooses the best API.
@ ForceUseEpoll
(Linux only) Tries to use epoll
@ ForceUseIOURing
(Linux only) Tries to use io_uring (failing if it's not found on the system)
Asynchronous I/O (files, sockets, timers, processes, fs events, threads wake-up) (see Async) AsyncEve...
Definition Async.h:1195
Time::Monotonic getLoopTime() const
Get Loop time.
Result associateExternallyCreatedFileDescriptor(FileDescriptor &outDescriptor)
Associates a previously created File Descriptor with the eventLoop.
Result wakeUpFromExternalThread()
Wake up the event loop from a thread different than the one where run() is called (and potentially bl...
Result runNoWait()
Process active requests if any, dispatching their completions, or returns immediately without blockin...
static Result removeAllAssociationsFor(SocketDescriptor &outDescriptor)
Removes association of a TCP Socket with any event loop.
void updateTime()
Updates loop time to "now".
static bool isExcludedFromActiveCount(const AsyncRequest &async)
Checks if excludeFromActiveCount() has been called on the given request.
Result associateExternallyCreatedSocket(SocketDescriptor &outDescriptor)
Associates a previously created TCP / UDP socket with the eventLoop.
Result blockingPoll(AsyncKernelEvents &kernelEvents)
Blocks until at least one event happens, ensuring forward progress, without executing completions.
void clearSequence(AsyncSequence &sequence)
Clears the sequence.
int getNumberOfSubmittedRequests() const
Obtain the total number of submitted requests.
Result submitRequests(AsyncKernelEvents &kernelEvents)
Submits all queued async requests.
void enumerateRequests(Function< void(AsyncRequest &)> enumerationCallback)
Enumerates all requests objects associated with this loop.
Result start(AsyncRequest &async)
Queues an async request request that has been correctly setup.
AsyncLoopTimeout * findEarliestLoopTimeout() const
Returns the next AsyncLoopTimeout that will be executed (shortest relativeTimeout)
void setListeners(AsyncEventLoopListeners *listeners)
Sets reference to listeners that will signal different events in loop lifetime.
Result dispatchCompletions(AsyncKernelEvents &kernelEvents)
Invokes completions for the AsyncKernelEvents collected by a call to AsyncEventLoop::blockingPoll.
void interrupt()
Interrupts the event loop even if it has active request on it.
Result wakeUpFromExternalThread(AsyncLoopWakeUp &wakeUp)
Wake up the event loop from a thread different than the one where run() is called (and potentially bl...
bool isInitialized() const
Returns true if create has been already called (successfully)
Result create(Options options=Options())
Creates the event loop kernel object.
static bool tryLoadingLiburing()
Check if liburing is loadable (only on Linux)
Result createAsyncTCPSocket(SocketFlags::AddressFamily family, SocketDescriptor &outDescriptor)
Creates an async TCP (IPV4 / IPV6) socket registered with the eventLoop.
Result close()
Closes the event loop kernel object.
Result createAsyncUDPSocket(SocketFlags::AddressFamily family, SocketDescriptor &outDescriptor)
Creates an async UCP (IPV4 / IPV6) socket registered with the eventLoop.
static Result removeAllAssociationsFor(FileDescriptor &outDescriptor)
Removes association of a File Descriptor with any event loop.
Result runOnce()
Blocks until at least one request proceeds, ensuring forward progress, dispatching all completions.
void excludeFromActiveCount(AsyncRequest &async)
Excludes the request from active handles count (to avoid it keeping event loop alive)
Result run()
Blocks until there are no more active queued requests, dispatching all completions.
void includeInActiveCount(AsyncRequest &async)
Reverses the effect of excludeFromActiveCount for the request.
int getNumberOfActiveRequests() const
Obtain the total number of active requests.
Starts an handle polling operation.
Definition Async.h:823
SC::Result start(AsyncEventLoop &eventLoop, FileDescriptor::Handle fileDescriptor)
Starts a file descriptor poll operation, monitoring its readiness with appropriate OS API.
Definition Async.h:692
Definition Async.h:698
Starts a file read operation, reading bytes from a file (or pipe).
Definition Async.h:688
FileDescriptor::Handle handle
The writeable span of memory where to data will be written.
Definition Async.h:711
Span< char > buffer
Callback called when some data has been read from the file into the buffer.
Definition Async.h:710
void setOffset(uint64_t fileOffset)
Sets the offset in bytes at which start reading.
Definition Async.h:719
uint64_t getOffset() const
The file/pipe descriptor handle to read data from.
Definition Async.h:715
Starts an asynchronous file system operation (open, close, read, write, sendFile, stat,...
Definition Async.h:997
SC::Result copyDirectory(AsyncEventLoop &eventLoop, StringSpan path, StringSpan destinationPath, FileSystemCopyFlags copyFlags=FileSystemCopyFlags())
Copies a directory from one location to another.
SC::Result removeEmptyDirectory(AsyncEventLoop &eventLoop, StringSpan path)
Removes a directory asynchronously.
SC::Result rename(AsyncEventLoop &eventLoop, StringSpan path, StringSpan newPath)
Renames a file.
SC::Result removeFile(AsyncEventLoop &eventLoop, StringSpan path)
Removes a file asynchronously.
SC::Result setThreadPool(ThreadPool &threadPool)
Sets the thread pool to use for the operation.
SC::Result read(AsyncEventLoop &eventLoop, FileDescriptor::Handle handle, Span< char > buffer, uint64_t offset)
Reads data from a file descriptor at a given offset.
SC::Result write(AsyncEventLoop &eventLoop, FileDescriptor::Handle handle, Span< const char > buffer, uint64_t offset)
Writes data to a file descriptor at a given offset.
SC::Result close(AsyncEventLoop &eventLoop, FileDescriptor::Handle handle)
Closes a file descriptor asynchronously.
Function< void(Result &)> callback
Called after the operation is completed, on the event loop thread.
Definition Async.h:1026
SC::Result copyFile(AsyncEventLoop &eventLoop, StringSpan path, StringSpan destinationPath, FileSystemCopyFlags copyFlags=FileSystemCopyFlags())
Copies a file from one location to another.
SC::Result open(AsyncEventLoop &eventLoop, StringSpan path, FileOpen mode)
Opens a file asynchronously and returns its corresponding file descriptor.
Definition Async.h:763
Starts a file write operation, writing bytes to a file (or pipe).
Definition Async.h:754
uint64_t getOffset() const
Returns the last offset set with AsyncFileWrite::setOffset.
Definition Async.h:791
FileDescriptor::Handle handle
The file/pipe descriptor to write data to.
Definition Async.h:783
SC::Result start(AsyncEventLoop &eventLoop, Span< const char > data)
Sets async request members and calls AsyncEventLoop::start.
void setOffset(uint64_t fileOffset)
Sets the offset in bytes at which start writing.
Definition Async.h:795
Function< void(Result &)> callback
Callback called when descriptor is ready to be written with more data.
Definition Async.h:781
Span< Span< const char > > buffers
The read-only spans of memory where to read the data from.
Definition Async.h:787
SC::Result start(AsyncEventLoop &eventLoop, Span< Span< const char > > data)
Sets async request members and calls AsyncEventLoop::start.
Span< const char > buffer
The read-only span of memory where to read the data from.
Definition Async.h:786
bool singleBuffer
Controls if buffer or buffers will be used.
Definition Async.h:788
Allows user to supply a block of memory that will store kernel I/O events retrieved from AsyncEventLo...
Definition Async.h:1173
Span< uint8_t > eventsMemory
User supplied block of memory used to store kernel I/O events.
Definition Async.h:1174
Starts a Timeout that is invoked only once after expiration (relative) time has passed.
Definition Async.h:303
SC::Result start(AsyncEventLoop &eventLoop, Time::Milliseconds relativeTimeout)
Sets async request members and calls AsyncEventLoop::start.
Time::Absolute getExpirationTime() const
Gets computed absolute expiration time that determines when this timeout get executed.
Definition Async.h:318
Function< void(Result &)> callback
Called after given expiration time since AsyncLoopTimeout::start has passed.
Definition Async.h:313
Time::Milliseconds relativeTimeout
First timer expiration (relative) time in milliseconds.
Definition Async.h:315
Starts a wake-up operation, allowing threads to execute callbacks on loop thread.
Definition Async.h:339
SC::Result start(AsyncEventLoop &eventLoop, EventObject &eventObject)
Sets async request members and calls AsyncEventLoop::start.
Function< void(Result &)> callback
Callback called by SC::AsyncEventLoop::run after SC::AsyncLoopWakeUp::wakeUp.
Definition Async.h:352
SC::Result wakeUp(AsyncEventLoop &eventLoop)
Wakes up event loop, scheduling AsyncLoopWakeUp::callback on next AsyncEventLoop::run (or its variati...
EventObject * eventObject
Optional EventObject to let external threads wait for the callback to end.
Definition Async.h:353
Executes work in a thread pool and then invokes a callback on the event loop thread.
Definition Async.h:944
Function< void(Result &)> callback
Called to execute the work in a background threadpool thread.
Definition Async.h:955
SC::Result setThreadPool(ThreadPool &threadPool)
Sets the ThreadPool that will supply the thread to run the async work on.
Definition Async.h:376
Starts monitoring a process, notifying about its termination.
Definition Async.h:367
SC::Result start(AsyncEventLoop &eventLoop, FileDescriptor::Handle process)
Sets async request members and calls AsyncEventLoop::start.
Function< void(Result &)> callback
Called when process has exited.
Definition Async.h:392
Base class for all async requests, holding state and type.
Definition Async.h:118
bool isCancelling() const
Returns true if this request is being cancelled.
AsyncRequest(Type type)
Constructs a free async request of given type.
Definition Async.h:156
Result start(AsyncEventLoop &eventLoop)
Shortcut for AsyncEventLoop::start.
uint16_t getUserFlags() const
Gets user flags, holding some meaningful data for the caller.
Definition Async.h:185
Function< void(AsyncResult &)> * getCloseCallback()
Returns currently set close callback (if any) passed to AsyncRequest::stop.
Definition Async.h:188
bool isActive() const
Returns true if this request is active or being reactivated.
bool isFree() const
Returns true if this request is free.
void disableThreadPool()
Disables the thread-pool usage for this request.
Type getType() const
Returns request type.
Definition Async.h:176
void setUserFlags(uint16_t externalFlags)
Sets user flags, holding some meaningful data for the caller.
Definition Async.h:182
Result executeOn(AsyncTaskSequence &task, ThreadPool &pool)
Adds the request to be executed on a specific AsyncTaskSequence.
Result stop(AsyncEventLoop &eventLoop, Function< void(AsyncResult &)> *afterStopped=nullptr)
Ask to stop current async operation.
void executeOn(AsyncSequence &sequence)
Adds the request to be executed on a specific AsyncSequence.
Type
Type of async request.
Definition Async.h:137
@ SocketSend
Request is an AsyncSocketSend object.
@ SocketReceive
Request is an AsyncSocketReceive object.
@ SocketAccept
Request is an AsyncSocketAccept object.
@ FileWrite
Request is an AsyncFileWrite object.
@ SocketSendTo
Request is an SocketSendTo object.
@ FileSystemOperation
Request is an AsyncFileSystemOperation object.
@ LoopTimeout
Request is an AsyncLoopTimeout object.
@ ProcessExit
Request is an AsyncProcessExit object.
@ FileRead
Request is an AsyncFileRead object.
@ SocketReceiveFrom
Request is an SocketReceiveFrom object.
@ FilePoll
Request is an AsyncFilePoll object.
@ LoopWakeUp
Request is an AsyncLoopWakeUp object.
@ SocketConnect
Request is an AsyncSocketConnect object.
@ LoopWork
Request is an AsyncLoopWork object.
Helper holding CompletionData for a specific AsyncRequest-derived class.
Definition Async.h:288
Base class for all async results (argument of completion callbacks).
Definition Async.h:258
const SC::Result & isValid() const
Check if the returnCode of this result is valid.
Definition Async.h:269
AsyncResult(AsyncEventLoop &eventLoop, AsyncRequest &request, SC::Result &res, bool *hasBeenReactivated=nullptr)
Constructs an async result from a request and a result.
Definition Async.h:260
void reactivateRequest(bool shouldBeReactivated)
Ask the event loop to re-activate this request after it was already completed.
Execute AsyncRequests serially, by submitting the next one after the previous one is completed.
Definition Async.h:236
bool clearSequenceOnError
Do not queue next requests in the sequence when current one returns error.
Definition Async.h:241
bool clearSequenceOnCancel
Do not queue next requests in the sequence when current one is cancelled.
Definition Async.h:240
Starts a socket accept operation, obtaining a new socket from a listening socket.
Definition Async.h:470
SC::Result start(AsyncEventLoop &eventLoop, const SocketDescriptor &socketDescriptor)
Sets async request members and calls AsyncEventLoop::start.
Starts a socket connect operation, connecting to a remote endpoint.
Definition Async.h:490
Function< void(Result &)> callback
Called after socket is finally connected to endpoint.
Definition Async.h:500
SC::Result start(AsyncEventLoop &eventLoop, const SocketDescriptor &descriptor, SocketIPAddress address)
Sets async request members and calls AsyncEventLoop::start.
Starts an unconnected socket receive from operation, receiving bytes from a remote endpoint.
Definition Async.h:653
Definition Async.h:610
SC::Result get(Span< char > &outData)
Get a Span of the actually read data.
Definition Async.h:616
Starts a socket receive operation, receiving bytes from a remote endpoint.
Definition Async.h:600
AsyncSocketReceive(Type type)
The Socket Descriptor handle to read data from.
Definition Async.h:635
SC::Result start(AsyncEventLoop &eventLoop, const SocketDescriptor &descriptor, Span< char > data)
Sets async request members and calls AsyncEventLoop::start.
Span< char > buffer
The writeable span of memory where to data will be written.
Definition Async.h:631
Function< void(Result &)> callback
Called after data has been received.
Definition Async.h:629
Starts an unconnected socket send to operation, sending bytes to a remote endpoint.
Definition Async.h:568
Starts a socket send operation, sending bytes to a remote endpoint.
Definition Async.h:524
Function< void(Result &)> callback
Called when socket is ready to send more data.
Definition Async.h:539
bool singleBuffer
Controls if buffer or buffers will be used.
Definition Async.h:545
SC::Result start(AsyncEventLoop &eventLoop, const SocketDescriptor &descriptor, Span< const char > data)
Sets async request members and calls AsyncEventLoop::start.
Span< Span< const char > > buffers
Spans of bytes to send (singleBuffer == false)
Definition Async.h:544
Span< const char > buffer
Span of bytes to send (singleBuffer == true)
Definition Async.h:543
SC::Result start(AsyncEventLoop &eventLoop, const SocketDescriptor &descriptor, Span< Span< const char > > data)
Sets async request members and calls AsyncEventLoop::start.
SocketDescriptor::Handle handle
The socket to send data to.
Definition Async.h:541
An AsyncSequence using a SC::ThreadPool to execute one or more SC::AsyncRequest in a background threa...
Definition Async.h:925
Atomic variables (only for int and bool for now).
Definition Atomic.h:97
An automatically reset event object to synchronize two threads.
Definition Threading.h:174
[UniqueHandleDeclaration2Snippet]
Definition File.h:78
Options used to open a file descriptor.
Definition File.h:49
A structure to describe copy flags.
Definition FileSystem.h:26
Wraps function pointers, member functions and lambdas without ever allocating.
Definition Function.h:19
Hides implementation details from public headers (static PIMPL).
Definition OpaqueObject.h:31
An ascii string used as boolean result. SC_TRY macro forwards errors to caller.
Definition Result.h:12
Low-level OS socket handle.
Definition Socket.h:163
AddressFamily
Sets the address family of an IP Address (IPv4 or IPV6)
Definition Socket.h:60
@ AddressFamilyIPV4
IP Address is IPV4.
Definition Socket.h:61
Native representation of an IP Address.
Definition Socket.h:104
View over a contiguous sequence of items (pointer + size in elements).
Definition Span.h:29
constexpr bool sliceStartLength(SizeType offsetInElements, SizeType lengthInElements, Span &destination) const
Creates another Span, starting at an offset in elements from current Span of specified length.
Definition Span.h:120
An read-only view over a string (to avoid including Strings library when parsing is not needed).
Definition StringSpan.h:37
A small task containing a function to execute that can be queued in the thread pool.
Definition ThreadPool.h:19
Simple thread pool that executes tasks in a fixed number of worker threads.
Definition ThreadPool.h:41
A native OS thread.
Definition Threading.h:118
Absolute time as realtime or monotonically increasing clock.
Definition Time.h:114
Type-safe wrapper of uint64 used to represent milliseconds.
Definition Time.h:44
Represent monotonically increasing time (use Monotonic::now for current time)
Definition Time.h:180