Adds progress Allocation to represent Decentralized Allocation Tree node.

[coollog]

Part of #1297. The Allocation class will be used by the ProgressEvent.

[loosebazooka]

Not specifically about this, but autobuilder is a great alternative to writing these out by hand.

[coollog]

Hmm, I'm not sure if AutoValue Builder is able to work for the single-method builder we have here?

[chanseokoh]

I see this will have no problem constructing the allocation tree.

However, I think I don't fully understand the intended usage in practice yet. I thought about some scenarios from the perspective of a developer trying to construct the whole tree with multiple depth of method calls and am left with some questions. For example, it isn't yet clear if whether it would be a caller or callee that should call newChild, if it is OK to pass the root or some child node to multiple, sequential method calls and/or pass the node down multiple call depth, if we can enforce matching the allocation units with the minimum number of newChild calls (or if it is necessary), what a callee should do if it just wants to mark completion (i.e., what info to emit as an event) when the allocation the callee got is a root node, etc. Perhaps better to ask these offline.

[chanseokoh]

So I see this example shows that the expect normal usage is to match the number of children and the parent allocation units. As I said in my previous comment, I am really curious how this can pan out or be enforced efficiently in practice. But I think we can move forward with this now, and I'd be able to see if the API will work out to minimize errors.

[coollog]

Yea, the user of the Allocation class will be responsible for sub-allocating the correct number of allocations. For example, for a task that knows it will launch 3 subtasks, it will first create its own allocation as 3 allocation units, and then launch the 3 subtasks, passing down its own allocation as the "parent" allocation, knowing that each of the subtasks will thus make a suballocation, resulting in 3 total suballocations.

[chanseokoh]

Yeah, in that example, what if the writer of one of the subtasks (think of as separate methods) that get the "parent" allocation doesn't have anything to report progress or if the writer simply wants to mark completion before returning using the given parent allocation node? Should it emit an event with the parent node and 1 allocation done? But, in turn, what if the subtask called other methods and propagated down the parent node as-is? In that case, if the sub-subtasks did the same thing as what the subtask did (emitting the event with the parent node and 1 allocation done), the progress will go over the allocated amount.

[coollog]

Yes, emitted an event with the parent node and 1 allocation done can work, or the subtask can create a suballocation and emit an event with all progress units in the suballocation. The allocation(s) are only to represent the subdivision of the overall progress and it will be up to the tasks to coordinate how to emit progress on those allocations (with the premise that parent tasks have power over child tasks) and up to the progress event listener to process the emitted progress in whichever way it chooses to do so (allow or disallow going over allocated amount, for eg.).

[chanseokoh]

with the premise that parent tasks have power over child tasks)

Yeah, I think this premise is required for this work well. When the premise is applied recursively, I think it implies having power over all descendants. For example, if you are some subtask at some point, and you call several long-running external methods in sequence, you don't really know about whose internals. So, you just pass the allocation node you have, but you basically have no idea how those will make use up the node. They may or may not consume 1 allocation, or more. And those external methods may in the same situation recursively. So, basically, it looks to me that we should have the premise that parent tasks should have an idea about all descendants.

[coollog]

Yeah, in our use case in the builder steps, this premise will be met by a constraint that

1. A task may only create at most one suballocation of the parent allocation passed to it, and
2. A task cannot pass the parent allocation on to subtasks