[FEAT] The Flow API

[iceBear67]

Flow —— A channel for transferring data among objects, also helps developers to write secure, reliable, and high-performance codes easily.

Prototype

We assume that there are two machines.

One is Furnace A, the other one is Compressor B.

FA polls items and produces results after some ticks. CB polls multiple items and produces compressed artifacts then.

• Tick FA
• FA => Push two items into a flow (by player)
• FA <= (Furnace is empty) Poll things from flow (1 item)
• FA -- Fire tick ++
• Tick CB
• CB <= Poll items
• CB -- Nothing found.
• Tick FA
• FA => FireTicks >= XX! Push productions into flow.
• FA -- Check items or end this tick
• Tick CB
• CB <= Poll items
• CB -- Collect...
• CB (Collect enough) => Push result.

In this example, you'll find that flow is a container that can simplify the item transferring process. The following concepts will explain this idea more clearly.

Class Definition

`Flow

Methods:

1. combine(Flow) Combines two flows into one. (parameter will be combined into original one)
2. publish(T) Publishes data into a flow. Subscribers will be notified first.
3. to(Consumer<T>) Polls data from flow, the amount is up to limit property.
4. to(Predicate<T>) While it is simliar to to(Consumer<T>), it enables the ability to return a boolean about whether it consumed the data.
5. pollFor(int) Polls data in a specified amount. As much as it can and no ArrayOutOfBoundException excepted.
6. peek() Peeks the latest data from the flow. For filtering purposes.
7. peekFor(int)Peeks some data from the top to specified location, no AOOBE excepted.
8. subscribe(Predicate) Subscribes new data from flow, also control removal if data is used during a callback. Dangerous

Polling

A pushes data into a flow, then B polls data in its tick.

Flow is not active except for subscribe. The only (also recommended) way to fetch data from flow is polling, which is lazy and synchronized (for most kinds of flow)

Except for sharing data, flows can be used as a container during its tick (e.g the furnace loads its data that was pushed in earlier codes but in the same tick). This makes flow to be more convenient (we'll explain this later)

Polling has its own rules. A poll always returns items as much as it can without AOOBE. While we provided pollFor(int) we still recommend using the to(lambda) method for polling data. By using such a lambda function, Flows are able to hide their details (i.e the poll limit, the recommended poll num) and control execution (Execute the lambda or not, even delegate it). Also, it causes less redundant pollings (for which is even possible to cause errors.) according to its strategy or something else.

So we'll "deprecate" pollFor or make some compile-time warning on it.

Properties

1. persistent. Determines whether the flow will be saved independently or not.
   **It may lead to duplicated data if users take it into states(states are already persistent). Use it only if the flow instance is out of persistent states, such as global-uses.
2. pollLimit The "suggested-poll counts", determines how much data can be transferred during one to()
3. type. The Class of transferred objects. It enables flows to make special supports such as for ItemStacks (See below) and serialization supports.
4. name The name of the flow. For debugging and verbosity.
5. bufferSize. Max data can be in the buffer. We can't publish if the buffer is already full. (default Int.MAX)

Special Support for Items

For most situations, our machines want to deal with one item(i.e amount == 1) at one time. Flow integrated this support and separates itemstacks while polling. It makes it easier to avoid interacting with item amounts, which possibly causes dupes.

DoubleFlow

Valhalla isn't ready yet. We still need to hand-specialize some flows. And for energy or signal transferring purposes, we introduce DoubleFlow. It's much similar to Flow, So I won't explain too much for that.

Others

1. Flows are always stateful to avoid polling new data instead of the long-existed data.
2. Flows are very lightweight, we should encourage users to try flow and write more reliable codes
3. Flows can integrate anything. Such as any container(i.e from vanilla or other tech mods), Inventories(mainly for [FEAT] GUI Framework #30 )