NOTES-TODO.txt

primary to-do list and notes/thoughts
=====================================


* FUTURE
    parse/etc.
        future parser:
            eliminate 'stream' class. only static methods
            pass around : (MemorySegment, offset, length)
                tho could use MemorySegment.byteSize() (size in bytes of segment)

            ValueLayout.

        data.get(ValueLayout.JAVA_BYTE, offset + i);

        // use memory segment / FFM
https://github.com/gunnarmorling/1brc/blob/main/src/main/java/dev/morling/onebrc/CalculateAverage_merykitty.java#L226
        try (var file = FileChannel.open(Path.of(FILE), StandardOpenOption.READ);
                        var arena = Arena.ofShared()) {
                    var data = file.map(MapMode.READ_ONLY, 0, file.size(), arena);
                    ...
                    'data' is a MemorySegment
                    }

                    Arena.ofConfined() would be appropriate for single thread
                         .close() closes it

            see: https://github.com/gunnarmorling/1brc/blob/main/src/main/java/dev/morling/onebrc/CalculateAverage_merykitty.java#L293
            parse method would take a MemorySegment
                MemorySegment data, long offset, int size
            String key = new String(this.keyData, i * KEY_SIZE, node.keySize, StandardCharsets.UTF_8);
                private static final ValueLayout.OfLong JAVA_LONG_LT = ValueLayout.JAVA_LONG_UNALIGNED.withOrder(ByteOrder.LITTLE_ENDIAN);

        var line = ByteVector.fromMemorySegment(BYTE_SPECIES, data, offset, ByteOrder.nativeOrder());
        long semicolons = line.compare(VectorOperators.EQ, ';').toLong();
                // not found; either EOF or key not in vector
                if (semicolons == 0) {
                    int keySize = BYTE_SPECIES.length();
                    while (data.get(ValueLayout.JAVA_BYTE, offset + keySize) != ';') {
                        keySize++;
                    }
                    var node = aggrMap.indexSimple(data, offset, keySize);
                    return parseDataPoint(aggrMap, node, data, offset + 1 + keySize);
                }

                            var nodeKey = ByteVector.fromArray(BYTE_SPECIES, aggrMap.keyData, bucket * PoorManMap.KEY_SIZE);
                            long eqMask = line.compare(VectorOperators.EQ, nodeKey).toLong();
                            long validMask = semicolons ^ (semicolons - 1);
                            if ((eqMask & validMask) == validMask) {
                                break;
                            }

* EXAMPLES
   done    - renaming built-in functions
   done    - replacing implicit functions (e.g., DATETIME with TEMPORAL)
   done    - simple implicit functions via lambdas
   done    - how to set default options for a function
   done    - error handling examples (error handler for fluent bundle)

   done - how to select on a list (cannot!!) but show how it can be accomplished by splitting messages into
            formatting items and selection

   done - locale selection and fallback example.
            have two locales, and show how to switch and what happens.
            e.g., english & french.
            see end of this document for additional info


    * wiki/readme for:
        - why Fluent vs. ICU::MF or MF2
        - list support & why that's important
        - how to read in FTL
        - locale fallback (see below)
        - why should not use for critical controls :)
        - feature highlights
        - explicitly note dependencies (just one)
            - why depends on ICU
                   1) plurals
                   2) number formatter w/skeletons
        - work on readme.md ****
           - thread safety
            FFR is threadsafe and shareable
            cache : not, but could be (if so written)
            functions : are, but if written to not be, must take precaustions
            coudl have more than one bundle for same lang (per thread); most of the work (BEFORE rendering) is
                in parsing FTL to create the FluentResource

    * OSSRH release
    * release notification on reddit / also to fluent group (GH project) AFTER OSSRH release


* SIMD
    * note performance pitfalls
    * code improvements
        * SIMD blend overkill for skipBlankBlock
    * CRLF detection: determine best approach: load 2 vectors vs. shifting masks.
        also performance tests with CRLF line endings
    * doc notes: scalar first, simd optional (scalar fallback).
        SIMD not always faster, and much slower startup.

* FEATURE HIGHLIGHTS
    - experimental SIMD ...
    - list handling
    - JDK21 compatible

* Rendering Performance Optimizations (for next minor version)
    * Measurements: need good JMH tests for message rendering
        * effects of caching/cache performance
        * focus on common methods
            String, Numbers, Lists, DateTime/Temporal
    * potentially consider, depending upon measurements: bytecode generation or (likely easier) StringConcatFactory
        https://github.com/mtumilowicz/java9-string-concat?tab=readme-ov-file
        https://kotlinlang.org/docs/whatsnew1520.html#string-concatenation-via-invokedynamic
    * better pre-sizing of StringBuilders ? keep track of size in pattern element? even if only approximate


* Locale fallback
     just use ICU:LocaleMatcher
        ICU:LocaleMatcher.Builder
     this would be provided by (end-user-supplied!)
        * directly specified in code
        * or, supplied by a configuration file with supported locales
        * or, by scanning file system/classpath
     LocaleMatcher.getBestLocale() to get closest-matching Locale

     NOTE: this is all handled by ICU; we should give an example BUT not much to code here.

     using LocaleMatcher, get tags, and file/resource would be:
         *  recommend a naming format: (tentative):
             myFtlFile_en-GB.ftl
             {basename}_{languagetag}.{extension}