Add getContentsAsync methods to Clipboard

[jonahgraham]

Obtaining data from the clipboard is fundamentally an asynchronous operation, the event loop, at least at the OS level, needs to run for the data to become available.

This PR proposes new API that provides asynchronous equivalents of getContents methods called getContentsAsync that return CompleteableFutures.

This new API will allow SWT API consumers to interact better with the clipboard when the OS (window system) API is actually implemented in an asynchronous manner.

GTK3 and cocoa provides API that spins the event loop as needed so that a synchronous looking API can be provided to the user of the API. For example, in SWT we use gtk_clipboard_wait_for_contents which spins the loop in the GTK library itself
here

GTK4 does not provide such an API and leaves it to the user of the API to spin the event loop.

Win32 is somewhat of a hybrid. The API appears synchronous, but SWT needs to spin in a couple of places, such as
getData

Part of #2598 and #2126

[github-actions]

Test Results

  115 files    115 suites   11m 37s ⏱️
4 562 tests 4 546 ✅ 16 💤 0 ❌
  311 runs    308 ✅  3 💤 0 ❌

Results for commit 3420711.

♻️ This comment has been updated with latest results.

[jonahgraham]

One aspect I am unsure of is the naming here.

We can't simply overload getContents because the only difference in the new method is the return type. But in java.util.concurrent it seems generally the Async suffixed methods imply running in a separate (asynchronous) thread.

Am I overthinking this, is getContentsAsync a good name? @laeubi any thoughts?

[HeikoKlare]

Am I overthinking this, is getContentsAsync a good name?

In my opinion, thinking about that name is definitely valuable. It might be mistaken as "I just have to wait long enough for the contents to be available" (as it would be the case with the referenced concurrent Java API using an Async suffix). E.g., you could use getContentsAsync().join(), but that will never return if no one else spins the event loop. There is a slight analogy to Display#asyncExec() as that will also only be executed if you spin the event loop (though there is no CompletableFuture but you could, e.g., put a barrier in the passed runnable), just that Display#asyncExec() is more common and users usually know how it works.
On the other hand, I have no better name proposal and a sophisticated documentation of what "async" means in this case is given by the Javadoc, so unless someone has a better proposal I would be fine the currently proposed name.

[jonahgraham]

I would be fine the currently proposed name.

Great. Thanks @HeikoKlare for having a look and sharing your thoughts here. I'll leave this open a little bit longer in case anyone else has thoughts or concerns.

[laeubi]

I would be fine the currently proposed name.

Great. Thanks @HeikoKlare for having a look and sharing your thoughts here. I'll leave this open a little bit longer in case anyone else has thoughts or concerns.

I'm also fine with that name, an alternative I often use in this case is simply omit the "get" and use the "shortform" what is the CompletableFuture<?> contents(); but not everyone is happy with that and its more a personal preference.

In any case every java developer should be aware that joining a feature is always a bad thing and a source of code-smell.

[jonahgraham]

alternative I often use in this case is simply omit the "get" and use the "shortform"

I am pretty fond of this too, especially when making new API these days. I like "ProcessBuilder" in Java in this way.

[akurtakov]

I believe this is ready to go . Only request from my side is to add a reference in getContents javadoc refering to the new method and guiding users to choose it.

[jonahgraham]

I believe this is ready to go . Only request from my side is to add a reference in getContents javadoc refering to the new method and guiding users to choose it.

Done: See diffs here