diff --git a/readme.txt b/readme.md
similarity index 52%
rename from readme.txt
rename to readme.md
index 7efc2df9..08c5a7e1 100644
--- a/readme.txt
+++ b/readme.md
@@ -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
+embedded and PC systems. Simply fetch a binary package for your toolchain or integrate the build
+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:
+Doxygen:
+Examples:
+Tests:
+Cmake-stable:
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
+Aurora Macro Sugar: https://git.reece.sx/AuroraSupport/AuroraRuntime/src/branch/master/Include/AuroraMacros.hpp
+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
+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
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.
+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
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
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):
+ Most STL implementations have generally awful to unnecessarily inefficient abstraction.
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):
+ Moving to or from linux, macos, bsd, and win32 under varous kernels, there is no one
standard (even in posix land) for the key thread primitives.
-Bonus point NT:
+Bonus point NT (3):
The userland CriticalSection/CV set of APIs suck, lacking timeouts and try lock
-Bonus point UNIX:
+Bonus point UNIX (4):
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
+4: Consider using loop sources, perhaps with the async subsystem, in your async application.
+Performance of loop sources will vary wildly between platforms, always being generally worse than
+the high performance primitives. They should be used to observe kernel-level signalable resources.
+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
+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)
+Aurora provides a bring your own container and shared pointer model overloadable in your configuration header.
+
+```
+Types:
+ AuSPtr
+ AuWPtr
+ AuUPtr
+Functions:
+ AuSPtr AuMakeShared(Args&& ...)
+ AuSPtr AuUnsafeRaiiToShared(T *)
+ AuSPtr AuUnsafeRaiiToShared(AuUPtr)
+Macros:
+ AuSPtr AuSharedFromThis()
+ AuWPtr 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
+However, strict C codebases would need to shim to C, perhaps using AuUnsafeRaiiToShared to convert T\*s to unsafe `AuSPtr`s, the namespaced C++ functions
+It should be noted that most language bindings and generator libraries (^swig, v8pp, nbind, luabind) work with shared pointers.
+
## 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
+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
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
+- block on write
+- delegate write to end of network frame on write
+- read with an all-or-nothing flag and an async flag
- read with an asynchronous stream callback
-- peaking
+- peaking
- 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
+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.
-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:
+[0] == '.' = cwd
+[0] == '~' = platform specific user directory / brand / Profile
+[0] == '!' = platform specific app config directory / brand / System
+[0] == '?' = ., !, or ~
+.. = go back
+/ = splitter
\ = 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 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
+namespace. Featuring promises, thread group pooling, functional-to-task wrapping, and
+task-completion callback-task-dispatch idioms built around 3 concepts.
-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,
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
+specific APIs. Fetch system language and country backed by environment variables, the OS
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
+ 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
+ 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,
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
+ 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