Update 'readme.md'
This commit is contained in:
parent
a28f5285f0
commit
244f7718dd
@ -2,9 +2,9 @@
|
||||
|
||||
## AuroraRuntime
|
||||
|
||||
The Aurora Runtime is an extensive platform abstraction layer for cross-platform C++ development
|
||||
across embedded and PC systems. Simply fetch a binary package for your toolchain or integrate
|
||||
our build scripts into your applications build pipeline to get started.
|
||||
The Aurora Runtime is an platform abstraction layer for cross-platform C++ development targeting<br>
|
||||
embedded and PC systems. Simply fetch a binary package for your toolchain or integrate the build<br>
|
||||
scripts into your applications build pipeline to get started.
|
||||
|
||||
## Features
|
||||
|
||||
@ -26,45 +26,51 @@ our build scripts into your applications build pipeline to get started.
|
||||
|
||||
## Links
|
||||
|
||||
API:
|
||||
Doxygen:
|
||||
Examples:
|
||||
Tests:
|
||||
Cmake-stable:
|
||||
API: <br>
|
||||
Doxygen: <br>
|
||||
Examples: <br>
|
||||
Tests: <br>
|
||||
Cmake-stable:<br>
|
||||
Build Pipeline:
|
||||
|
||||
## Utilities
|
||||
|
||||
Aurora Runtime provides macros and some template apis to make writing common C++ idioms and
|
||||
tricks easier.
|
||||
Aurora Sugar: https://git.reece.sx/AuroraSupport/AuroraRuntime/src/branch/master/Include/AuroraUtils.hpp <br>
|
||||
Aurora Macro Sugar: https://git.reece.sx/AuroraSupport/AuroraRuntime/src/branch/master/Include/AuroraMacros.hpp <br>
|
||||
Aurora Overloadable Type Declerations: https://git.reece.sx/AuroraSupport/AuroraRuntime/src/branch/master/Include/AuroraTypedefs.hpp
|
||||
|
||||
|
||||
## Logging
|
||||
|
||||
Aurora Runtime does not attempt to implement your favourite production logger. We instead
|
||||
implement a subscription based log message dispatcher with some default backends including
|
||||
a file logger, Windows debug logging, Windows conhost stdin/out using UTF-8, UNIX stdin/out
|
||||
respecting the applications codepage, a wxWidgets toolkit GUI, and hopefully more to come.
|
||||
Additionally, consoles that provide an input stream can be used in conjunction with the parse
|
||||
Aurora Runtime does not attempt to implement your favourite production logger. We instead<br>
|
||||
implement a subscription based log message dispatcher with some default backends including<br>
|
||||
a file logger, Windows debug logging, Windows conhost stdin/out using UTF-8, UNIX stdin/out<br>
|
||||
respecting the applications codepage, a wxWidgets toolkit GUI, and hopefully more to come. <br>
|
||||
Additionally, consoles that provide an input stream can be used in conjunction with the parse<br>
|
||||
subsystem to provide basic command-based deserialization, tokenization, and dispatch.
|
||||
|
||||
## Loop [WIP]
|
||||
|
||||
Aurora Runtime offers a main loop that connects multiple input sources into one delegate.
|
||||
Timers, semaphores, mutexes, events, X11, FDs, Win32 msg loop, macos, IPC, file aio handles, and
|
||||
async runner main loop sources will be supported. This equates to a cross-platfom equivalent of
|
||||
Aurora Runtime offers a main loop that connects multiple input sources into one delegate. <br>
|
||||
Timers, semaphores, mutexes, events, X11, FDs, Win32 msg loop, macos, IPC, file aio handles, and<br>
|
||||
async runner main loop sources will be supported. This equates to a cross-platfom equivalent of<br>
|
||||
NT's MsgWaitForMultipleObjects in the form of a MainLoop object and a WaitMultiple function.
|
||||
|
||||
## Thread Primitives
|
||||
|
||||
The Aurora Runtime provides platform optimized threading primitives inheriting from a featureful
|
||||
The Aurora Runtime provides platform optimized threading primitives inheriting from a featureful<br>
|
||||
IWaitable interface. Each method is guaranteed.
|
||||
|
||||
- IWaitable
|
||||
::TryLock()
|
||||
::Lock(timeout)
|
||||
::Lock()
|
||||
::Unlock()
|
||||
|
||||
```
|
||||
IWaitable
|
||||
bool TryLock()
|
||||
void Lock(relativeTimeoutInMilliseconds)
|
||||
void Lock()
|
||||
void Unlock()
|
||||
```
|
||||
|
||||
Included high performance primitives
|
||||
- arbitrary IWaitable condition variable
|
||||
- condition mutex : IWaitable
|
||||
- condition variable : IWaitable
|
||||
@ -77,152 +83,147 @@ IWaitable interface. Each method is guaranteed.
|
||||
IWaitable ::GetWrite()
|
||||
- spinlocks
|
||||
|
||||
We acknowledge and wish to solve the two problems cross-platform developers frequently face.
|
||||
|
||||
Problem one:
|
||||
Most STL implementations have generally awful to unnecessarily inefficient abstraction.
|
||||
Problem one (1): <br>
|
||||
Most STL implementations have generally awful to unnecessarily inefficient abstraction. <br> <br>
|
||||
Defer to libc++'s abuse of spin while (cond) yield loops and msvc/stl's painfully slow
|
||||
std::mutex and semaphore primitives.
|
||||
|
||||
Problem Two:
|
||||
Moving to or from linux, macos, bsd, and win32 under varous kernels, there is no one
|
||||
Problem Two (2): <br>
|
||||
Moving to or from linux, macos, bsd, and win32 under varous kernels, there is no one <br>
|
||||
standard (even in posix land) for the key thread primitives.
|
||||
|
||||
Bonus point NT:
|
||||
Bonus point NT (3): <br>
|
||||
The userland CriticalSection/CV set of APIs suck, lacking timeouts and try lock
|
||||
|
||||
Bonus point UNIX:
|
||||
Bonus point UNIX (4): <br>
|
||||
No wait multiple mechanism
|
||||
|
||||
|
||||
If you wish to wait on primitives in an asynchronous application, look into runloop sources
|
||||
|
||||
|
||||
1, 2, 4: Use the high performance AuThreadPrimitives objects<br>
|
||||
4: Consider using loop sources, perhaps with the async subsystem, in your async application. <br>
|
||||
Performance of loop sources will vary wildly between platforms, always being generally worse than <br>
|
||||
the high performance primitives. They should be used to observe kernel-level signalable resources.<br>
|
||||
4 ex: Windows developers could use loop sources as a replacement to WaitMultipleObjects with more overhead
|
||||
|
||||
|
||||
## Strings
|
||||
|
||||
Currently using a typedef of `std::string`, the Aurora Runtime is looking to switch over the
|
||||
string type over to `tiny-utf8`'s string type. **All** strings are assumed to be UTF-8.
|
||||
The Aurora Runtime defines an `AuString` type as an `std::string`; however, it should be assumed this type<br>
|
||||
represents a binary blob of UTF-8. Looking to switch to `tiny-utf8` for UTF-8 safety.
|
||||
|
||||
## Memory
|
||||
|
||||
Assumes using AuSPtr, AuWWPtr = std::xxx or app wide redefinition to an alternative smart ptr
|
||||
implementation. Macros AU_WEAK_FROM_THIS, AU_SHARED_FROM_THIS provide decltype(this) Au[W/S]Ptrs
|
||||
when the std::enable_shared_from_this or equivalent is utilized. UnsafeRaiiToShared converts raw
|
||||
pointers to ownerless shared pointers for use with shared apis.
|
||||
User-overloadable type declerations and generic access utilities are defined [utilities](## Utilities)<br>
|
||||
Aurora provides a bring your own container and shared pointer model overloadable in your configuration header.
|
||||
|
||||
```
|
||||
Types:
|
||||
AuSPtr<Type_t>
|
||||
AuWPtr<Type_t>
|
||||
AuUPtr<Type_t, Deleter_t>
|
||||
Functions:
|
||||
AuSPtr<T> AuMakeShared<T>(Args&& ...)
|
||||
AuSPtr<T> AuUnsafeRaiiToShared<T>(T *)
|
||||
AuSPtr<T> AuUnsafeRaiiToShared<T>(AuUPtr<T>)
|
||||
Macros:
|
||||
AuSPtr<This_T> AuSharedFromThis()
|
||||
AuWPtr<This_T> AuWeakFromThis()
|
||||
AuFunction<...> AuBindThis(This_t *::?, ...)
|
||||
```
|
||||
|
||||
Most Aurora Runtime APIs provide generic new and release functions should you not need the overhead of reference counting or unique ptrs <br>
|
||||
However, strict C codebases would need to shim to C, perhaps using AuUnsafeRaiiToShared to convert T\*s to unsafe `AuSPtr<T>`s, the namespaced C++ functions <br>
|
||||
It should be noted that most language bindings and generator libraries (^swig, v8pp, nbind, luabind) work with shared pointers. <br>
|
||||
|
||||
|
||||
## IO
|
||||
|
||||
The IO subsystem consists of three interfaces, StreamReaders, StreamWriters, and
|
||||
ArbitraryStreamReaders; an FS namespace; a network namespace; and an optional
|
||||
async file io namespace.
|
||||
[TODO] Summary
|
||||
|
||||
A note about encoding; stdin, file encoding, text decoders, and other IO resources work with
|
||||
codepage UTF-8 as the internal encoding scheme. String overloads and dedicated string APIs in
|
||||
the IO subsystem will always write BOM prefixed UTF-8 and attempt to read a BOM to translate
|
||||
A note about encoding; stdin, file encoding, text decoders, and other IO resources work with<br>
|
||||
codepage UTF-8 as the internal encoding scheme. String overloads and dedicated string APIs in<br>
|
||||
the IO subsystem will always write BOM prefixed UTF-8 and attempt to read a BOM to translate<br>
|
||||
any other input to UTF-8.
|
||||
|
||||
## NIO
|
||||
|
||||
The networking stack supports a handful of architectural paradigms
|
||||
- block on write
|
||||
- delegate write to end of network frame on write
|
||||
- read with an all-or-nothing flag and an async flag
|
||||
The networking stack supports a handful of architectural paradigms<br>
|
||||
- block on write<br>
|
||||
- delegate write to end of network frame on write<br>
|
||||
- read with an all-or-nothing flag and an async flag<br>
|
||||
- read with an asynchronous stream callback
|
||||
- peaking
|
||||
- peaking<br>
|
||||
- async read/write pump whenever or all
|
||||
|
||||
## FIO
|
||||
|
||||
We suspect most developers delegate IO to a worker thread, don't wish to deal with an extern
|
||||
async model nor want excessively buffered streams, therefore the FIO API implements a read/write
|
||||
seekable C-like file stream interface. An alternative AFIO namespace exists for the few platforms
|
||||
that provide posix AIO, win32 overlap, or linux's io syscalls.
|
||||
|
||||
File stream, buffered read/write utilities, stat, exists, copy, move, remove, and readdir backed
|
||||
by the best platform specific blocking apis.
|
||||
|
||||
Guaranteed 64-bit file pointer safety across seek functions.
|
||||
|
||||
[Open]Write to a file under a path of missing directories guarantees creation of missing sub
|
||||
directories.
|
||||
[TODO] async, fio abstraction, utf8 read/write, blob read/write, stat, dir recursion, stream abstraction
|
||||
|
||||
### Paths
|
||||
|
||||
We assume all paths are messy. Incorrect splitters, double splitters, relative paths, and
|
||||
keywords are resolved internally. No such URL or path builder, data structure to hold a
|
||||
tokenized representation, or similar concept exists in the codebase. All string 'paths' are
|
||||
simply expanded, similar to MSCRT 'fullpath'/UNIX 'realpath', at time of usage.
|
||||
We assume all paths are messy. Incorrect splitters, double splitters, relative paths, and<br>
|
||||
keywords are resolved internally. No such URL or path builder, data structure to hold a <br>
|
||||
tokenized representation, or similar concept exists in the codebase. All string 'paths' are<br>
|
||||
simply expanded, similar to MSCRT 'fullpath'/UNIX 'realpath', at time of usage. <br>
|
||||
|
||||
Path tokens include:
|
||||
[0] == '.' = cwd
|
||||
[0] == '~' = platform specific user directory / brand / Profile
|
||||
[0] == '!' = platform specific app config directory / brand / System
|
||||
[0] == '?' = ., !, or ~
|
||||
.. = go back
|
||||
/ = splitter
|
||||
Path tokens include:<br>
|
||||
[0] == '.' = cwd<br>
|
||||
[0] == '~' = platform specific user directory / brand / Profile<br>
|
||||
[0] == '!' = platform specific app config directory / brand / System<br>
|
||||
[0] == '?' = ., !, or ~<br>
|
||||
.. = go back<br>
|
||||
/ = splitter<br>
|
||||
\ = splitter
|
||||
|
||||
## Aurora Async
|
||||
|
||||
The Aurora Runtime offers an optional asynchronous task driven model under the Aurora::Async
|
||||
namespace. Featuring promises, thread group pooling, functional-to-task wrapping, and
|
||||
task-completion callback-task-dispatch idioms built around 3 concepts.
|
||||
|
||||
Jobs are callee provided interfaces providing ::onSuccess/onFailure(const in, const out)
|
||||
Tasks are an internally-provided interface providing optional<out> onFrame(const in)
|
||||
WorkItems adapt a job and a task into one concept. They take a minimum sched delay, promises,
|
||||
initial delay, and other requirements; to provide a Dispatch routine capable of handling
|
||||
promises and other abstract developer requirements
|
||||
The Aurora Runtime offers an optional asynchronous task driven model under the AuAsync <br>
|
||||
namespace. Featuring promises, thread group pooling, functional-to-task wrapping, and <br>
|
||||
task-completion callback-task-dispatch idioms built around 3 concepts. <br>
|
||||
|
||||
We will not define a standard way to use these concepts.
|
||||
For instance, there is no guidance on whether or not you should use public task state structs
|
||||
and request a Task pointer from a public API or you should accept Job and return a WorkItem;
|
||||
when or where you should dispatch; whether or not to use C or Functional interfaces.
|
||||
Example:
|
||||
|
||||
## Proccesses
|
||||
|
||||
The Aurora Runtime provides worker process monitoring, worker Stdin/out stream redirection,
|
||||
The Aurora Runtime provides worker process monitoring, worker Stdin/out stream redirection,<br>
|
||||
process spawning, file opening, and url opening functionality.
|
||||
|
||||
## Locale
|
||||
|
||||
Encoding and decoding UTF-8, UTF-16, UTF-32, GBK, GB-2312, and SJIS support using platform
|
||||
specific APIs. Fetch system language and country backed by environment variables, the OS
|
||||
Encoding and decoding UTF-8, UTF-16, UTF-32, GBK, GB-2312, and SJIS support using platform<br>
|
||||
specific APIs. Fetch system language and country backed by environment variables, the OS<br>
|
||||
system configuration, the unix locale env variable, and/or the provided overload mechanism.
|
||||
|
||||
## Philosophies
|
||||
|
||||
- Assume C++17 language support in the language driver
|
||||
|
||||
- To avoid reinventing the wheel, solve the large issues nobody is tackling, and accept
|
||||
third party solutions weighted against relevant legal constraints and developer time
|
||||
|
||||
- Solve the large issues nobody is tackling. To avoid reinventing the wheel accept third party <br>
|
||||
solutions when the pros (developer time) weighted against the negatives (legal, bulk) makes
|
||||
sense.
|
||||
- Use AuXXX type bindings for std types, allow customers to overload the std namespace
|
||||
|
||||
- Keep the code and build chain simple such that any C++ developer could maintain
|
||||
their own software stack built around aurora components.
|
||||
|
||||
- Dependencies should be cross-platform friendly
|
||||
It is recommended to fork and replace any legacy OS specific code with equivalent
|
||||
AuroraRuntime concepts
|
||||
|
||||
- Dependencies, excluding core reference algorithms (eg compression), must be rewritten
|
||||
and phased out over time.
|
||||
|
||||
- Dependencies should not be added if most platforms provide some degree of native support
|
||||
Examples: -> Don't depend on a pthread shim for windows; implement the best thread
|
||||
primitives that lie on the best possible api for them
|
||||
Don't depend on ICU when POSIX's iconv and Win32's multibyte apis cover
|
||||
everything a conservative developer cares about; chinese, utf-16, utf-8,
|
||||
- Dependencies should not be added if most platforms provide some degree of native support<br>
|
||||
Examples:<br>
|
||||
-> Don't depend on a pthread shim for windows; implement the best thread <br>
|
||||
primitives that lie on the best possible api for them <br>
|
||||
Don't depend on ICU when POSIX's iconv and Win32's multibyte apis cover<br>
|
||||
everything a conservative developer cares about; chinese, utf-16, utf-8,<br>
|
||||
utf-32 conversion, on top of all the ancient windows codepages
|
||||
|
||||
|
||||
- Dependencies should only be added conservatively when it saves development time and
|
||||
provides production hardening
|
||||
Examples: -> Use embedded crypto libraries; libtomcrypt, libtommath
|
||||
-> While there are some bugs in libtomcrypt and others, none appear to
|
||||
cryptographically cripple the library. Could you do better?
|
||||
-> Use portable libraries like mbedtls, O(1) heap, mimalloc
|
||||
-> Writing a [D]TLS/allocator stack would take too much time
|
||||
-> Linking against external allocators, small cross-platform utilities, and
|
||||
so on is probably fine
|
||||
-> Shim libcurl instead of inventing yet another http stack
|
||||
provides production hardening <br>
|
||||
Examples:<br>
|
||||
-> Use embedded crypto libraries; libtomcrypt, libtommath<br>
|
||||
-> While there are some bugs in libtomcrypt and others, none appear to <br>
|
||||
cryptographically cripple the library. Could you do better?<br>
|
||||
-> Use portable libraries like mbedtls, O(1) heap, mimalloc<br>
|
||||
-> Writing a [D]TLS/allocator stack would take too much time<br>
|
||||
-> Linking against external allocators, small cross-platform utilities, and <br>
|
||||
so on is probably fine <br>
|
||||
-> Shim libcurl instead of inventing yet another http stack <br>
|
||||
Loading…
Reference in New Issue
Block a user