sync: add split method to the permit types

[vvvviiv]

Add detach method to SemaphorePermit and OwnedSemaphorePermit.

Motivation

Assume there are two tasks named A and B, and we have a Semaphore with two permits.

A needs one permit, B needs two permits at first and one permit later.

If B executes first, it calls acquire_many to get a SemaphorePermit with two permits. After doing some work, one of the permits is unnecessary for B to continue the work, but we can only release all permits at once.

In this case, A has to wait until B finishes all works or B releases its two permits and acquires one permit again to continue the remaining work without blocking A.

Since we have the merge method, I believe that the corresponding inverse operation is reasonable.

Solution

Adds the detach method to SemaphorePermit and OwnedSemaphorePermit to allow us to detach some permits from the source permits.

[mox692]

Thank you, such an api seems reasonable to me. I left a comment regarding the api.

[Darksonn]

I think split would be a better name.

[vvvviiv]

I think split would be a better name.

Well, I chose the name split at first, but I changed my mind because of some reasons:

1. split has several close meanings. Without reading the document, a user may think that split(n) means to split one SemaphorePermit into n SemaphorePermits. However, detach hints that we are separating some permits from one SemaphorePermit that has more permits. (I'm not a native speaker of English, maybe I misunderstood something?)
2. The split method name is widely used. By the first impression of other split methods, it's easy to cause some misunderstanding like the example in 1.

But if you insist, the name split is also ok with me.

[Darksonn]

You use the name detach to mean "detach from these permits", but to me, the name sounds like you are detaching the permits from the semaphore itself. So to me, detach sounds more like an alternate name for the forget method.

I suggested split because it's the opposite of merge.

So I'd prefer split or some third name if you have other suggestions.

[vvvviiv]

It's finished.

[mox692]

Looks good to me.