Bounded map/array support (`io.avaje.json.JsonWriter`/`JsonReader`)

[mechite]

(on the topic of writing MessagePack, CBOR implementations using avaje's great
generation etc).

I want the ability to pre-determine the size of maps and arrays.

That is, it can be more of an optimization offering in the API, and not used
by JSON, or anything other unbounded formats.

It would look something like this (same goes for arrays):

private static final class ThrowableAdapter
        implements JsonAdapter<Throwable> {
        ...
        @Override
        public void toJson(JsonWriter writer, Throwable value) {

            // I want to hard code the number of fields, in this map
            writer.beginObject();

            // writer.object(2);
            //
            // You don't need to end the object
            //
            // 1. JSON parsers can forcefully close it after 2 insertions in
            //    this example, but they have to track the state of this.
            //
            //    JSON can just throw an UnsupportedOperationException instead.
            //
            // 2. Binary formats that have these bounded headers, can utilize
            //    this, but support the other approach using "lazy evaluation".
            //
            //    That is very slow and wastes a lot of memory.
            //    The entire contents being written is buffered, that way.
            //
            // 3. Binary formats can fail on the other approach, then.
            //
            // 4. avaje-jsonb generates something that can use this feature,
            //    using a boolean comparison at runtime, in the constructor
            //    of the JsonAdapter.
            //
            //    "Are you using a bounded format?"
            //    Otherwise, I see no way of making it so "pluggable" where one
            //    can just swap an application with zero re-compilation.

            writer.name("type");
            writer.value(value.getClass().toString());

            writer.name("message");
            writer.value(value.getMessage());

            // This is only needed if you used `begin*`
            writer.endObject();
        }
        ...
}

I was originally thinking that maybe my JsonAdapter can store state, and I can
count how many times that someone inserted fields, etc, and then just write
headers based on what we expect toJson to do, etc.

This feature is not needed at all, and it goes against the very name of this
project - avaje jsonb.

---

I just wanted to start a discussion on what I can do with generation / writing,
for a non-JSON format, while potentially getting the pluggability which the
Jackson implementations provide.

This is where it sucks that an annotation processor cannot really
"have dependencies" in any nicely supported way.

It would be really much easier, if avaje-jsonb was pluggable, and I can supply
an optimized path for MessagePack serialization, some interface & member methods
toMessagePack/fromMessagePack.

For Avaje in that case, it could have been "as simple" as opening up some parts
of the generator, to allow me to just plug-in my own methods, implements
clauses, etc.

---

Thinking about the problem, there are many ways I can think about entering the
issue, and I think mainly it would just be nice to offer a very fast
serialization mechanism while staying pluggable and making it "as easy" as
removing some SPI implementation JARs at runtime.

---

With the new FFM API, not using it for foreign-memory but using it for unsafe
memory operations, ala sun.misc.Unsafe, one is able to implement a binary
format like MessagePack, with zero-copy readers, etc:

0x83 [map of 3 elements]
	  name -> John Doe       <-- we have the ability to just point to this,
	                             and give a `String`, meaning we never copied
	                             the buffer (from the network stream, etc).
	  age -> 0x14

This works if we have access to a ByteBuffer or MemorySegment to feed our
data directly into, our reader is fed the data in a "streaming" way later, and
can just return pointers, zero-copy.

The buffer can be shared across an application, and then there is absolutely
zero GC pressure at all for serialization. We completely take this factor out,
and store basically no data "dynamically" on the heap.

In a virtual-thread world - we ask for the thread-local buffer upon connection,
we load our data into it, run the parser over to access what we need - there are
no copies, and we only ever allocated the single buffer - combine that with the
lightweight thread, and we have almost no short-lived objects.

Everything there is request scoped, or you could even re-use a buffer for
multiple requests if synchronization was faster than allocation (I doubt).

The allocation of avaje's "meta" objects, such as the json adapter classes,
this is ny-on free honestly, especially stateless objects that may be the "same
every time".

---

Writing FFM-based parsers that can really utilize the JIT to full potential and
give us the best of all worlds? It's simple enough to actually do this, if it
would work.

It'd be cooler to just try a zero-copy JSON project, before combining this with
binary protocols to try and squeeze every drop out of our serialization.

With the efficiency of binary protocols over the network, we can get
tiny payloads + really quick computation - compressed JSON is small too but it
will not be as simple to parse, if binary is done right.

Protobuf & Flatbuffers are examples where we just drop the human-readable
aspect, and completely denote an entire model statically. This is annoying to
maintain compared to JSON+XML formats that have stood the test of time, just
due to their "implementation agnosticism" for being human-readable.

I am not super knowledgeable about any of this and the above is just my
gatherings from "thinking about the problem" to try and see how far we can push
performance.

I see no motivation to use an "agnostic" binary format, other than performance,
and if gzip+JSON could match or surpass performance no matter what, then the
idea can go into the trash-bin.

In theory, declarative/static stuff like Protobuf can be really fast, and the
binary sizes would be half of msgpack/cbor/etc, even smaller than JSON etc.
Bad "Schema evolution" for me is the biggest negative side-effect.

---

TL:DR; adding the feature described at the very top, and some extra notes about
zero-copy and "potential".

^{CC @rbygrave @SentryMan, feel free to close if you are not enthusiastic}

[mechite]

In thought about it, JSON can support this API perfectly fine too.
Incrementing int/long is free

@SentryMan if you don't want this, close it.
I'm probably going to fork (for this purpose) and drop the 'json specific-ness'

[rbygrave]

Just to say, I think this is effectively desiring:

writer.beginObject();

to be able to feature toggle over to:

writer.beginObject(2); // when the object has 2 fields

and for arrays, binary protocols tend to have both variable sized and fixed sized arrays so desiring:

writer.beginArray();

to be able to feature toggle over to:

// for fixed size array
writer.beginArray(theCollection.size());

// for variable sized array
writer.beginArray(); // variable sized

There are a few ways that this could be feature toggled on, for example the existence of a type (in the classpath accessible to the annotation processor) like:

• io.avaje.jsonb.generator.featuretoggle.IncludeObjectSize
• io.avaje.jsonb.generator.featuretoggle.IncludeArraySizeAlways

... add a maven dependency with that type in it to feature toggle on that code gen feature (as one relatively simple way to do it)

[mechite]

existence of a type

Yeah... this is where I thought it was debatable because processors have some trouble having dependencies of their own, in some cases.

An @IncludeObjectSize annotation, which a seperate generator (org.example.some_binary_format_generator) could just write out, could trigger a round for avaje-jsonb-generator, etc, but it probably means some (maybe too far out of scope) internal changes to jsonb
EDIT - or just for the user to put on a module/package.

[rbygrave]

If the changes are limited to being able to feature toggle "size" for objects and arrays like:

writer.beginObject(2); // when the object has 2 fields

writer.beginArray(theCollection.size()); // fixed sized arrays 

... then I think it's ok for jsonb to consider support for that with a view that it allows folks to feature toggle that on somehow and experiment with binary protocols. I think that is "simple enough" that we'd be ok with it.

Is the scope limited to those 2 changes?

[mechite]

Is the scope limited to those 2 changes?

I think this is the only thing that needs to change.

Changing the generation with a hard toggle-switch would remove the runtime 'swappability', but I think that's something to worry about after there's at least one high-performance adapter, to be honest.

Also noting that the default implementation of IncludeObjectSize/IncludeArraySizeAlways could be fully functional under JSON, so it could likely still be 'swappable for debugging your application'

(by just removing the custom adapter JARs (implementing avaje spi) from class-path/module-path)
I guess debugging is really the only motivation for it being swappable

[rbygrave]

Yeah, it would be an interesting experiment. For strings we can just get the length and copy the bytes and avoid the escaping. I can't remember which is it .. but I remember there is some serialisation that at runtime could switch between binary and human readable [so you'd generally use binary and then could dynamically swap to human readable for debugging/support at runtime].

[mechite]

@rbygrave maybe Amazon Ion is what you were trying to recalll?

EDIT - there is also just the Jackson binary formats, where msgpack, CBOR, Avro, etc encoders can mostly work but not 100% runtime swappable (they didn't use SPIs) but someone in their own program can just make an SPI for the ObjectMapper instance etc, and just swap things due to reflective nature

[mechite]

@SentryMan can we reopen this? feel free to assign me

[thatcomputerguy0101]

Is a feature flag even necessary for this? A beginObject(2) call isn't that different from a beginObject(names) call, and the default implementation for beginObject(int length) could be to just call beginObject().

[mechite]

the default implementation for beginObject(int length) could be to just call beginObject().

We could make it flip a boolean when you use a bounded method, to make the endObject call a no-op if the underlying implementation is indeed a bounded format, and then we reach a point where the "bounded generation" works fine for "unbounded formats" like JSON, but then vice versa does not apply.

That means I guess it should stay a flag, because we don't want to needlessly start using beginObject(int length) for JSON? Which is the focus of the library I guess.

P.S. I haven't worked on this because I'm busy and don't need it yet, but I want it, the time will come