Point out cancelation semantics in fromCompletableFuture scaladoc

[danicheg]

No description provided.

[armanbilge]

Sorry, we should retarget this change at series/3.5.x branch so it will be released sooner. Thanks btw!

[armanbilge]

I'm not sure about the comment about "thread interruptions". The JavaDoc for CompletableFuture#cancel says this:

mayInterruptIfRunning - this value has no effect in this implementation because interrupts are not used to control processing.

https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html#cancel-boolean-

WDYT about this?

Suggested change

	* Note that cancelation is cooperative, and it's up to the `CompletableFuture` to respond to
	* interruption requests and handle cancelation appropriately. This means that if the
	* `CompletableFuture` computation is uncancellable (for example, it doesn't handle `Thread`
	* interruptions), there will be no 'fire and forget' semantics and by satisfying backpressure
	* guarantees, cancelation will wait for computation to complete.
	* @note Cancelation is implemented by invoking the `CompletableFuture`'s `cancel()` method.
	* It is up to the `CompletableFuture` to handle cancelation appropriately and indicate it has done so.
	* This means that if the `CompletableFuture` indicates that it did not cancel, there will be no
	* "fire-and-forget" semantics. Instead, to satisfy backpressure guarantees, the `CompletableFuture`
	* will be treated as if it is uncancelable and the fiber will fallback to waiting for it to complete.

[danicheg]

Uh-oh, probably the part on thread interruptions is really wrong. I like your rephrasing generally, but I would like to leave the reference that cancelation is cooperative. There are a few more mentions about it within CE's scaladocs. And maybe we need to remove the part on using the cancel method on CF since it's the only way to cancel it, and very unlike smth will change for Java's API.

[armanbilge]

but I would like to leave the reference that cancelation is cooperative. There are a few more mentions about it within CE's scaladocs.

Ahh, I'm sorry, you are right! This is used in many places.

cats-effect/docs/concepts.md

Line 102 in 6a6db8f

First off, is *cooperative*. When one fiber calls `cancel` on another fiber, it is effectively a request to the target fiber. If the target fiber is unable to cancel at that moment for any reason, the canceling fiber asynchronously waits for cancelation to become possible. Once cancelation starts, the target fiber will run all of its finalizers (usually used to release resources such as file handles) before yielding control back to the canceler. Conversely, `interrupt` always returns immediately, even if the target `Thread` has not actually been interrupted.

I was confusing with "cooperative polling" 😅 TIL.

Ok, how about this? (Feel free to make your own revision and push to the branch :)

Suggested change

	* Note that cancelation is cooperative, and it's up to the `CompletableFuture` to respond to
	* interruption requests and handle cancelation appropriately. This means that if the
	* `CompletableFuture` computation is uncancellable (for example, it doesn't handle `Thread`
	* interruptions), there will be no 'fire and forget' semantics and by satisfying backpressure
	* guarantees, cancelation will wait for computation to complete.
	* @note Cancelation is cooperative and it is up to the `CompletableFuture` to respond to the request
	* by handling cancelation appropriately and indicating that it has done so.
	* This means that if the `CompletableFuture` indicates that it did not cancel, there will be no
	* "fire-and-forget" semantics. Instead, to satisfy backpressure guarantees, the `CompletableFuture`
	* will be treated as if it is uncancelable and the fiber will fallback to waiting for it to complete.

[danicheg]

Seems great to me. Thanks for adjusting and pushing this forward.

[danicheg]

@armanbilge do you merge changes from series/3.x to series/3.5.x? Or it's done conversely?

[armanbilge]

We merge from series/3.5.x -> series/3.x.

[armanbilge]

Thank you, this is an excellent thing to note!