Yet Another Concurrency Discussion

[lokka30]

As we're working on v2, we have the liberty to do anything we want to the code.

Particularly, which concurrency system(s) we wish to use should be agreed upon.

Here are some of our choices:

• CompletableFuture
• Ivan's SimplifiedFuture
  • Blocks usage of join, get, etc.
  • Adds 'withDefault' utility.
  • See an unfinished version of the class here.
  • See an example usage here.
• Subscribers
  • Easy to understand, very messy to use.
• Others?..

---

Tagging those who may be interested (all Treasury contributors) - let me know if you wish to opt-out of these: @MrIvanPlays @Jikoo @MrNemo64 @creatorfromhell @A248 @yannicklamprecht @portlek @Sliman4 @NoahvdAa @Geolykt

[A248]

As imperfect as CompletableFuture may be, I much prefer it to creating a type such as "SimplifiedFuture." CompletableFuture, for all its flaws, is the library standard for future objects. It is interoperable and flexible: feature-complete but certainly not elementary.

I'm well-acquainted with CompletableFuture's failings. However, plugin developers need to learn to use CompletableFuture as it is. The Paper, Sponge, and Velocity APIs make use of CompletableFuture, and likewise many plugin APIs. We should rely on CompletableFuture for Treasury -- or perhaps CompletionStage, if the interface is to be preferred.

Calling join is an elementary mistake, but it is actually one which is easily remedied. Spotted once, developers are likely to learn the purpose of join (at least, they have in my experience). The real pitfall of CompletableFuture is its exception handling: failing to attach an exception handler to the end of a CompletableFuture chain causes the exception to be swallowed.

[lokka30]

Thank you very much for posting your opinion A2, and glad you agree Jikoo. Small remedies can be quite easily provided through documentation, so that is not of too much concern to me; I assume that developers who don't read documentation think they already know everything, so that's on them.

I have updated my original post to further discuss Ivan's SimplifiedFuture idea. Potentially, both could be used in parallel. I'll need to write side-by-side example implementations using both Future systems respectively to compare them from a user standpoint: how easy they are to read, write, understand.

[A248]

Honestly speaking, I find very little wrong with the SimplifiedFuture API in isolation. Its provision of a default exception handler (printing the exception stacktrace) is superior to CompletableFuture's no-op default behavior when an exception occurs. The method names are reasonably understandable, and while the API is somewhat limited compared to CompletableFuture -- e.g., SimplifiedFuture does not allow specifying the Executor for dependent tasks -- SimplifiedFuture performs well its intended purpose, which is to provide an easy-to-use future-based API.

However, I believe SimplifiedFuture remains on the wrong track, because it attempts to establish a competing API to CompletableFuture. java.util.concurrent.CompletableFuture is by now well-established in the ecosystem. Learning it ought to be a one-time affair. Creating a Treasury-specific futures API betrays a tunnel vision surrounding plugin development.

Even beginner developers will engage in various other APIs, none of which will use SimplifiedFuture. Rather than simplify their learning, you would introduce an additional hurdle by requiring them to learn a niche concurrency API. SimplifiedFuture is unlikely to become a widespread standard.

Experienced plugin developers will expect a quality API from a new framework such as Treasury: confronting them with a competing futures API suggests a preference to. At least, this was my own reaction when I first read of EconomySubscriber. Learning a new concurrency interface, even if its similar in use to CompletableFuture, is wholly redundant and requires unnecessary mental overhead. The methods map, flatMap, and handle all have differently-named equivalents in the CompletableFuture API. The SimplifiedFuture API provides very little additional functionality beyond CompletableFuture. Consequently, I would expect most knowledgeable plugin developers to dismiss SimplifiedFuture altogether.

With all this in mind, I think it would be detrimental to break from the CompletableFuture standard. I mean that, not only should CompletableFuture be the default for Treasury's APIs, but also we should not even provide or encourage the use of SimplifiedFuture as a Treasury API. If a developer wishes to use SimplifiedFuture rather than CompletableFuture, then SimplifiedFuture should be made into its own library. A conversion method in such library would allow users to turn a CompletableFuture into a SimplifiedFuture. Treasury should favor CompletableFuture as the default; any competing concurrency interfaces should be made into separate libraries.

As far as Treasury is concerned, however, we should stay with a standard concurrency interface -- CompletableFuture the top candidate -- rather than attempt to establish an alternative concurrency API within our very limited area of Minecraft economy plugins.

[lokka30]

Thank you again A2, I am very grateful that you have thoroughly explained your position. As it stands I agree with your thoughts. If anyone shares this thought, please up-vote and/or like A2's original comment, otherwise, please add a comment or reply to discuss your opinion.

[A248]

Also, I think we should be considering the implications of our choice here on API return values and error handling.

What I mean is that EconomySubscriber, the current API in use, requires handling transaction failure. For example, if the user has insufficient balance to withdraw funds, the transaction will fail with a EconomyFailureReason indicating negative balances not supported / insufficient funds available.

With CompletableFuture, however, it is easy to miss handling an EconomyException. We may want to consider using a result object like Vault does: for example, returning a EconomyResult which can be either success or failure. Using an exception makes API users somewhat prone to overlook the failure case.

So, if we decide to switch to CompletableFuture, we should be thinking of how to indicate transaction failures. I'm inclined to believe using exceptions will make API users omit proper failure handling, and that we should switch to returning a result wrapper.

[MrIvanPlays]

something like CompletableFuture<TransactionResult> ??

[lokka30]

We have decided to use CompletableFutures. For the (account and currency) migration system, we will be also using @MrIvanPlays's Process library.

Thanks so much for your input @A248!