sophistsolutions/stroika

Modern C++ made easy

Stroika v2.1

Stroika is a modern, portable, thread-savvy, C++ application framework. It makes writing high performance C++ applications easier by providing safe, flexible, modular building blocks.

Stroika provides a layer on top of the Standard C++ Library, with simpler to use (higher level) classes, more safety checking guarantees, and a wider domain of applicability. But those Stroika classes seamlessly integrate with standard C++ classes, and your code can easily use as much of either library as preferences dictate.

Stylistically, Stroika differs from the Standard C++ Library, boost, and many other C++ libraries, in that it (relatively) embraces object oriented abstractions over template-based genericity (see Stroika-Approach-To-Performance.md). The abstraction of type hierarchies is better suited to how people reason, and templates and concepts - while powerful - can be fiddly and obscure programmer intent. Also, Stroika emphasizes separation of interface from implementation: carefully documenting the interface in the headers, and separating the implementation to other files.

Stroika is comprised of 2 layers: the Foundation, which provides building-block classes applicable to most applications, and a series of domain specific Frameworks which provide a rich collection of code in different domains.

The Frameworks depend on the Foundation; Foundation modules frequently depend on each other; but Foundation layer code contains no dependencies outside of the Foundation (except on the Standard C++ Library, and various ThirdPartyComponent libraries optionally included or referenced, like openssl).

Quality

• Nearly all public interfaces and methods are well documented; implementations are clear and well commented.
• Thoroughly integrated assertions (including thread-safety assertions) help document and enforce usage patterns (without performance cost in production builds).
• Each release is tested with Valgrind (helgrind, memcheck), Google Sanitizers (TSAN, UBSAN, and ASAN), Github CodeQL, and a variety of platforms and compilers, as well as a large body of regression tests (including most documentation examples) to help assure library correctness.
• Sample applications help show common use cases (like building a web server into your app to deliver web-service content and APIs).
• Quick start using pre-built Docker containers (for Windows, and Linux).

Stroika Foundation provides

• Cache classes (a variety of different caching/memoizing strategies directly supported).
• Characters classes (simpler to use - especially with UNICODE - Strings class, with functional style mappings - to ToString<template>() for most Stroika objects).
• Container classes (Collection, Queue, Mapping, Sequence, Set, and much more, each with rich variety of backend implementations).
• DataExchange (VariantValue, rich collection of data format serializer/deserializers - like JSON, object to/from serialization mappings, and much more).
• Execution pattern classes (external process runner, synchronization patterns, blocking queue, thread pools, and much more).
• Networking support (high level socket wrappers, Web client fetching).
• Simple, elegant streams library, with adapters for cryptography, compression, text transforms, etc.
• Seamless integration (object oriented wrappers respecting Stroika's safety and adapter rules) with many important libraries , including: boost, libcurl, lzma sdk, openssl, sqlite, xerces, zlib (e.g. wrap a compression stream - using for example zlib).
• and more...

Stroika Frameworks provides

• network measurement
• SSDP/UPnP
• system performance monitoring
• text editing/word processor
• web server
• web services
• and more...

Trade-offs

Stroika's biggest strength is also its biggest weakness:

• There are smaller, more focused libraries that do many of the things Stroika does. Being single purpose is a form of modularity (good) and allows for easy adoption/integration. But libraries that do anything of any complexity must create their own infrastructure for a wide variety of building block problems (e.g. Xerces has its own stream classes, pistache date classes, etc). And if you have two such libraries, they are unlikely to interact seemlessly, and their support classes (for stuff like date and streams above) certainly won't.
• Stroika takes the approach of building its functionality in layers, leveraging other components (e.g. Streams and Containers) in lower layers (as well as standardized C++ libraries). This slightly increases the cost of adopting Stroika for something small (because pulling one thing in pulls many things in), but then pays dividends as you use it to accomplish a second or third task.

Versions

• Stroika v3 development has started, and requires C++20 or later.

• Stroika v2.1 is stable (in maintainance), and requires C++17 or later. Version 2.1 also conditionally supports many C++20 features (such as three-way-comparison etc, if available).

• Stroika v2.0 is very stable, and requires C++14 or later. Stroika v2.0 is used to power a wide variety of open source and commercial applications.

Compilers / Platforms regularly tested/supported

• Linux, MacOS, Windows

• Stroika v2.1

  Tested on x86, arm (+m1), gcc 8 thru gcc 12, clang 6 thru clang 14, Visual Studio.Net 2017, Visual Studio.Net 2019 and Visual Studio.Net 2022, XCode 13, 14, 15.

• Stroika v2.0

  Tested on x86, arm, gcc 5 thru gcc 8, clang 3 thru clang 6, XCode 8 thru 9.

CI System Integration

• Github Actions

  Branches	Status
  v2.1-Release		.github/workflows/build-N-test-v2.1-Release.yml
  v2.1-Dev		.github/workflows/build-N-test-v2.1-Dev.yml

Random Features

• Vanilla make based builds
• Portable API (targets windows/mac/unix), and multiple processors

Summary

For more details on individual release changes, see:

    Release-Notes.md

"Getting Started", build instructions, design and other documentation:

     Documentation/

Looking through the samples is also a good way to start:

    Samples/

Please report bugs/issues at:

    http://stroika-bugs.sophists.com

stroika's Issues

Writeup definition of Minimal threadsafty and how obehct read/write threadsayt

 Writeup definition of Minimal threadsafty and how obehct read/write threadsayt

unix gcc compile options/valgrindish

 Add compile options for
o –fthread-santiizer
o -fsanitize=address
o -fsanitize=thread.

valgrind/Linux issue with threads - probably real bug

clang++ / valgrind issue

CLANG+++++

[](17 seconds) [34] Foundation::Execution::Threads (../Builds/DefaultConfiguration/Test34)
[Succeeded](0 seconds) [35] Foundation::Execution::Other (../Builds/DefaultConfiguration/Test35)

(tresting – thjis may only fail with enable-trace-to-file and if so – it maybe an issue with trace messages (to file) durinag  a thread abort callback (signal)

valgrind -q --track-origins=yes --tool=memcheck --leak-check=full --suppressions=DefaultValgrindSuppressions.supp ../Builds/DefaultConfiguration/Test34

issue seems to be iterating through contianers from signal handler – maybe use stl directly for this?

Further improve valgrind testing/usage

Make it easier to run regtest for mem leaks, building a no-block-allocation build or adding knowlege of our block allocation system to valgrind (there are extension points for this).

qStroika_Foundation_Memory_SharedPtrSupportsRValueReferences_ bug with gcc

document or debug (maybe defer for gcc -) qStroika_Foundation_Memory_SharedPtrSupportsRValueReferences_ issue

IterablefromIterator<> cleanup

I THINK IterableFromIteraotr<> now documented enough to make this clear.

1>  I can use IterableFromIteartor<> tdirectly – and use its CONTEXT_FOR_EACH_ITERATOR feature – passing in the base iterator – or even the base iterable (mapping) to call make iterator on (probab;ly better).

 And/Or I can fix Creategeneraotr so that COULLD be used if I want.
It needs its API changed to function<function<…optkna>>> and hten the context object ??? Maybe I don’t have enuf. Maybe need a code hook? Or mayben the virtual (void/void variant where I call Make my own iterator) is good enuf.

CLEANUP CODE>…

Mapping<> needs Values() method – like Keys ()!!!!

Add math.PinInRange() function

So I can replace logic like:
min (max (yearDiff, 0.0f), 100.0f);

with a more intuitively named function
double year = PinInRange (yearDiff, 0.0f, 100.0f);

(does same thing - just clearer).

(from http://bugzilla/show_bug.cgi?id=747)

WaitableEvent::TryWait

Maybe add TryWait() on waitable event – like Wait() – but returns bool instead of throw, and then redo that TryWait as base, and do Waits() that throw is simple inline wrappers.

SafeSequence<> - maybe approach to thread safety

 maybe “SafeSequence<
“SafeSequence<> “ : Sequence<> - and that mimics each API and assignemt. For ALL – its thressafe rep. But SafeSequence (and SafeXXX for each subclass) – does envelope threasasafety. A bit like my experimental Contianer::Optional<> code.
o Then – ASSIGNEMNTs all work for data mebers (they are all safe) – but the args to functions aren’t and don’t pay costs!!!

StringBuilder::InsertAt

TraceContext emit nothing optional feature (when nothing inside)

 add feature to TraceContext class – so it emits NOTHING EXCPET if anything would have happened (been emitted) inside.

ProcessRunniner exception behavior on failed runs (exit non-zero)

 ProcessRunnienr –docs and excpetion behavior – on exit (1) – non-zero extit – generate exception instead of oding nothing for synchronous returning result modes of operation, or have option to ignore exit code.

Logger::WindowsEventLogAppender event source name

Logger::WindowsEventLogAppender

CTOR NEEDS kEventSourceName[]  =   _T ("xxxtest");

Add Mapping<> Regtest for Keys() – at least minimal one…

Add Mapping<> Regtest for Keys() – at least minimal one…

Consider if SharedPtr<> should take optional template param saying locking strategy

SOON will (optionally through template param) support 'lock flag' so can be used automatically threadsafe copies.
* (STILL MSUST THINK THROUGH IF MAKES SENSE)

arg would be mutex or SpinLock, or extenrallylocked?

Container CTOR optimization

Container CTORs that call AddAll() CAN do variant that optimizes – doesn’t do LOCKING – since one ref in CTOR. That can make a number of important use cases much better!

String::Irep::Clone () method should never get called?

String::Irep::Clone () method should never get called?

(because of new readonly string api)

Sequence<>InsertAt/Insert

Review SequenceAPI – DOCUMENT that Insert() is basically InsertAt ();
Sequnce::Insert (should have overload taking an iterator to insert at that point refered to by iterator). Like Insert (it.CurrnetIndex()); But even more uimportant ehre cuz we don’t (yet) have it.CurrentIndex()

Bijection read validator

 Make sure bijection has ‘validator’ used in reading in data so it doesn’t crash if given bad data but throws.

PathName class

Make PathName a class with String CTOR (no explicit). Then make various public functions in that module methods.

Do DEPRECATED for exiingt public functions there.

shared_mutex WaitableEvent evaluate

See if
http://en.cppreference.com/w/cpp/thread/shared_mutex
makes Stroika WaitableEvent useless?

Mapping<>::Image

Add method Iterable Image () - returns a set (maybe say return set not iterable?) of items

•          which are the 'target' of this mapping (all the VALUES collected in a set). Note in docs - range
  

•          is the containing set of plusaible possible values, but image is the set of actual values
  

Possible thread safety / cleanup/performance change (containers)

 New TEMPLATED optional params to CONCRETE container likes like Mapping_Array<> LOCKER.
o One value will be
 Std::mutex
 Execution::SpinLock
 ExternallySynchonized
• (but no lock SIMILAR to SpinLock except in RELASE mode does nothing, but in DEBUG mode sets falg on log but asserts not already set, and unlock unsets falg
• So caller can create an EXNTERALLYSYNCHONZIED (UNLOCKED) container instance, and get in debug mode checking that its threadsafe, but in real runtmode (release mode) runs as fast as possible (no locking)

DOCUMENT RATIONALE FOR ITERATOR OWNER

DOCUMENT RATIONALE FOR ITERATOR OWNER:

Iterators iterate over something (if not in reality, at least conceptually

 When you iterate over an interable, its illegal to deletet that iterable. However, the underlying REP may be deleted/unreferenced (dealt with how??? – assigned in other threads while iterating – tahts what new XXX #define is for)
 But remains ILLEGAL to delete the iterator container until all objects iterating over it
 We LOGICALLY are iterating of an iterable container, but in fact, behind the scenes – are itearing over iterep rep shared_pointes. The reason the sematncs of owners are important, ius becasuse when we do shared_rep cloning (break references) – we have to be able to re-assocatied running iterators with the RIGHHT iterable rep.

_SafeReadWriteRepAccessor optimized so doesn’t do needless copy

 Make sure _SafeReadWriteRepAccessor optimized so doesn’t do needless copy back
(really already done but must do optimziatio so don’t copy of refcount != 1 , but if !=2 and oldrep= newrep (ro close)…

>>> GETREP STRING COUNT 1 VERSUS 2 THING.
    I THINK SAFE IF WE SAVE
    Cnt = getRefCnt()
    If (cnt > 2 or (cnt == 2 and filterable->get() != facessor.get ()) {
        Breakreferences\    
    }
    // only risk is before entry to code – refcount WAS 2 (two real diff owners and we need to clone)
    // and our envelope gets overwritten before we do this check (very small window) – but we check count  and THEN check if ptrs diff then we must breakref. Reason != test Ok is no way to have frep.get () go back to pointing to us cuz only refptr is hidden in accessor (til end).

Array Concrete class uses realloc - improper object construction rules (ok for POD)

CRITICAL BUG – ARRAY CODE USE REALLOC.
o OK if type is PODTYPE, but otherwise CANNOT USE – SO FIX!!!

Containers MultiMap

At least add placeholder for MultiMap

Maybe make SharedByValue<TRAITS>::ReadOnlyReference a public top level memory type

Maybe make SharedByValue::ReadOnlyReference a public top level memory type

Bijection As/Inverse tests dsioabled.

Fix Bijection As/Inverse regtests

Consider adding IDM (identity management) Framework

Consider IDM (identity management) Framework
 Identity Objects
o GUIDS(opaue)
 Permission Objects
o Opaue
 Integrate with third party systems to find identities (LDAP, RADIUS, OpenID, SSL-ClientClient)
 Integrate with third party systems to store permissions
 See general enough to replace HFWS impl
 Consider needs of Block – and see if what I can come up with is sufficient for them (and maybe suggest they use this)
 Provide private impl of ID->Permissions mapping (simple table) and lookup to gen permissions tokens (objects0
 Framework for validation of permissions (given identities)
 Integrate with web-framework

add missing methods like Inverse/and Domain etc returning iterables for Mapping/MultiSet etc.

 add missing methods like Inverse/and Domain etc – stuff that returns subiteraotrs (like TallyUnique does) for mapping, tally, bijection and any place we still have assertnotimplemtend on these thigns.

_SafeReadWriteRepAccessor DTOR makeiterator reace?

Document race with _SafeReadWriteRepAccessor DTOR and makeIteraotr

NOTE – conflict between SafeReadWriteAccessorRep and MkaeIterator() – race – no interlock – so you can get replaced rep object which loses iterator rep!!! tracking!!!

code to review

Why
template
inline Sequence::Sequence (Sequence&& s)
: inherited (static_cast < inherited&& > (s))
{
_AssertRepValidType ();
}

DON’T UNDERSTAND WHY static_cast<inherited&&> needed on windows ??? sometimes – instead of move<inhierted>

Make clean and make clobber don’t seem to work on unix! Bad – not losing .o files for librairy!

Make clean and make clobber don’t seem to work on unix! Bad – not losing .o files for librairy!

Major rework of exceptions support/exceptions classes

SPEND A LITTLE TIME THINKING ABOUT EXCEPTION STUFF
>> first read BS (stroustprup) book
 And probably next make StringException subclass from std::exception
 And make sure all my excpetions (or most) subclass of StringException
o (maybe rename StringExcpetion to just Exception)


 ExceptionPropagateHelper must be redone using new C++11 features

CheckedConverter_ValueInRange exception cleanup

        typename RANGE_TYPE::ElementType  CheckedConverter_ValueInRange (typename RANGE_TYPE::ElementType val, const RANGE_TYPE& r)
        {
            typename    RANGE_TYPE::ElementType useVal    =   Private_::CheckedConverter_Range_Helper_Pinner_ (val, RANGE_TYPE::TraitsType::kLowerBound, RANGE_TYPE::TraitsType::kUpperBound);
            if (not (RANGE_TYPE::TraitsType::kLowerBound <= useVal)) {
                Execution::DoThrow (BadFormatException ());
            }
            if (not (useVal <= RANGE_TYPE::TraitsType::kUpperBound)) {
                Execution::DoThrow (BadFormatException ());
            }

…. Throw more informative exception saying value n outside range a..b.

qStroika_Foundation_Traveral_IteratorUsesStroikaSharedPtr

Debug why qStroika_Foundation_Traveral_IteratorUsesStroikaSharedPtr fails. Could help performance.

block allocation docs

write docs on block allocation versus blockallocated versus blocaklocator

add todo to amke my blockaklocator work wtih stl.

doc advnates s of using blocka;locatored macorso etc

make skel

BUILD SKEL ½ working. Since in the middle of it, nicet o really get working.

SYSTEM_CONFIGURATION “SystemPerformance” Instrument

POSSIBLY ADD “SYSTEM_CONFIGURATION” “SystemPerformance” Instrument, and fill it with stuff from:
Read using new DataExcahnge/INI reader – the /etc/os-release file

Cleanup/decide on Containers::Optional versus Memory::Optional verus maybe stdc::optional

Do 2 variants of Optional<> one MINIMAL threadsafty (current and of ten used for perofrnance) and second ThreadSafe Optional<> useful in USER code – so structures can bemade of of optinal<> objects.

This IS now implemented .. and just evaluating and trying to decide how to organize.

Resolve handling of thread safety

This is hard, but needs to be fully done and documented and tested before we can open up to public use

Add portable resource compiler utility

• Add portable resourcecompiker utility. Don't use. Use eventually in db
module to load xsds avoiding no portable resource crap for unix and hfws

Used something LIKE this in X-Windws for bitmaps. Very simple to implement.

(from http://bugzilla/show_bug.cgi?id=806)

Lingusitcs/Words implematnion should use StringBuilder

Lingusitcs/Words implematnion should use StringBuilder

Review Boost

Experiment with and review Boost. Consider if/how to harmonize/integrate with Stroika

Mapping [] syntax leads to confusing bugs

SYNTAX
Mapping<String, VariantValue> tunersObjMap = topLevelObjMap[L"Tuners"].As<Mapping<String, VariantValue>> ();
Mapping<String, VariantValue> newTunersObjMap;
for (KeyValuePair<String, VariantValue> ti : tunersObjMap) {
Mapping<String, VariantValue> thisTunerMap = ti.fValue.As<Mapping<String, VariantValue>> ();
thisTunerMap[L"TECCurrentUpperBound"] = 6.0; //???
newTunersObjMap.Add (ti.fKey, thisTunerMap);
}
topLevelObjMap[L"Tuners"] = newTunersObjMap;

compiles but does wron thing.
Maybe have topLeve[] return const ref? advantage is then above cont compile. Deistangave is wrong semantics for threads…

ProcessRunner String arguments...

ProcessRunner requires args of SDKString. Probably a mistake. At least add overload taking string. Then maybe deprecate the SDKString version.

Consider/cleanup qStroika_Foundation_Traveral_IterableUsesStroikaSharedPtr

 qStroika_Foundation_Traveral_IterableUsesStroikaSharedPtr
o ….
o Add define for Iterables_Support-Threadsafe-Copy
o Add tempalted wrapper on any SHAREDPTR to support threadsafe copy (using threadlocks and uniuu_lco, two locks, and the lock function.
o Test with defined one way or the other (define for theradsafe) and compare performance numbers. Then decicde what todo.

DOCUMENT/IteratorOwner

>>> REDOCUMENT WHY WE HAVE THIS – AND PROBABLY DON’T LOSE BUT DOCUMENT ONE WAY OR OTHER OTHER WHERE WE DECLARE ITERATOROWNER!!!

“ITERATOR CONCEPTUALLY ITERATING OVER ITERABLE. THING ITERATING OVER NOT LOGICAL TO LOSE. BUT magic with reps is HIDDEN. Sharedptr stuff is just to do that hidden rep sharedptr magic”

PROBBALY LOSE ITERATOROWNER SUTFF /*
* NB - the suggestedOwnerID argument to MakeIterator() may be used, or ignored by particular subtypes
* of iterator/iterable. There is no gaurantee about the resulting GetOwner() result from the
* iterator returned.
*
* \em Design Note
* It might have been better design to make the argument to Iterable::Rep::MakeIterator ()
* be owner instead of suggestedOwner, and then require that it get tracked. But that would
* have imposed a memory (and copying) overhead on each iterator, and the current
* use cases for iterators dont warrant that.
*
* I think its good enough that particular subtypes - where tracking an owner makes sense and
* is useful, we be done. And when not useful, it can be optimized away.
*/
virtual Iterator MakeIterator (IteratorOwnerID suggestedOwner) const = 0;

• But thinkout carefully, and probably do one single remove in one commit so easier to REVERT if I decide I was wrong…