Implement and export isfull

[KronosTheLate]

This PR implements isfull(c::Channel).

It calls n_avail(c) ≥ c.sz_max in all cases. The original implementation was inspired by this comment, and therefore had a special case for unbuffered channels, which fell back to isready. I opted against this behaviour, because it fails to respect that an unbuffered channel is always full, in two important senses:
1) The number of elements available is greater than or equal the capacity
2) A call to put! will block

With the current implementation, the behaviour is simply understood and summarized in all cases by the start of the docstring:

Determines whether a Channel is full, in the
sense that calling put!(c, some_value) will block.

Shoutout to @SamuraiAku for their work in #40720, which helped me a lot on thinking this through, and remembering to change all relevant files. In particular, the detail around how c.cond_take.waitq may result in immediate unblocking, which is a really important caveat on a function that may be used to check if put!ing will block. However, for buffered channels, isfull is extremely close to putwillblock from #40720 (just a little better, with >= instead of ==), and for unbuffered channels it does not make much sense to see if put!ing will block.

This PR is created based on this "call to action".

Checklist:

• Entry in news
• Docstring with example
• Export function
• Mention in manual
• Entry in docs-reference

[KronosTheLate]

If this goes through, let's not forget #40921 (Equivalent functionality for RemoteChannel), which is waiting for #40720, even if merging this closes #40720.

[SamuraiAku]

@KronosTheLate Thanks for the shoutout!

[vtjnash]

Some possible word-smithing, to try to teach a user why they should never use this method(except of course, for cases where this query is useful):

Suggested change

	Note that if another task is currently waiting to `take!`
	a value from `c`, a call to `put!(c, some_value)` might
	immediately be unblocked, even if `isfull(c)==true`.
	This is particularly relevant for unbuffered channels.
	Note that it may be frequently the case that `put!` will not block after this returns
	`true`. Users must take precautions not to accidentally create live-lock bugs in their code
	by calling this method, as these are generally harder to debug than deadlocks. It is also
	possible that `put!` will block after this call, if there are multiple producer tasks
	calling `put!` in parallel.

[KronosTheLate]

While this looks like a good warning, it seems odd to me to describe the function as "test if full in the sense that put will block", and in the next sentence say that "maybie frequently this will ont block when returning true". If I read that, I would be left with a feeling of "okay, so which one is it". In that sense I like my original version, that just explains a case in which it might go wrong, and leaves it to the user to use that knowledge.

But the warning could be harder. What about

Note that a call to isfull generally occurs in a different instant than any call to put!. In particular, calling isfull and then subsequently put! guarantees that the calls occur at different instants. Therefore, the state of the channel may change between the calls, and generally isfull can not safely be used to see if a call to put! will in fact block.

A little verbose, but very clear and understandable IMO.

[vtjnash]

Your original version uses some words that have specific meanings for thread atomics, and those words don't apply in their defined technical sense (in particular "currently" is a term that seems to imply seq-cst guarantees, which does not hold here)

[vtjnash]

The word "instant" is also a seq-cst term, and does not apply here

[KronosTheLate]

I ment to say a different point in time. Would that be better?

[KronosTheLate]

I just read my latest suggestion again, and I like it a lot. It is short, precise, and understandable.

EDIT: But this would hardly be the first time I am overly happy with a phrasing of mine that may be illegible to others, so I am very curious about your opinion

[vtjnash]

You are describing seq-cst, which is an ordering that exists, and is the strictest ordering, but is not the ordering that applies here. Events do have temporal coordinates, and they do have a time at that temporal coordinate, but that does not imply anything about the sequence in which events happen at other coordinates in space.

[vtjnash]

So the problem with that warning is that the state of the channel also might have already been changed before isfull, but it wasn't observed until afterwards on this thread, as the memory ordering here is simply :monotonic. Or consider instead if there is another producer thread, it might already have the lock to insert a new value, but has not updated n_avail yet. Thus isfull is false, but the channel is already full. The :monotonic ordering forbids unstable observations (if a thread observes a value, then it will continue to observe that value until it is changed), but in isolation it doesn't enforce any other useful properties--that requires holding the channel lock. The put! and take! have acquire-release ordering, so that combination adds at least some additional properties in combination, but it is unclear if they are useful properties, unless you are writing stochastic algorithms (which is quite reasonable with threading to use algorithms that are resilient to such behaviors, such as exponential backoff).

[KronosTheLate]

I am surely in over my head regarding the details you are describing. If you were able to write something in roughly the format of my latest suggestion, but correct, I think that might be best. Otherwise, your original proposal is alright by me, though harder to read than would be ideal.

[KronosTheLate]

Some minor tweaks to your original proposal:

Note that it may frequently be the case that `put!` will
not block after this returns `true`. Users must take
precautions not to accidentally create live-lock bugs
in their code by calling this method, as these are
generally harder to debug than deadlocks. It is also
possible that `put!` will block after this call 
returns `false`, if there are multiple producer
tasks calling `put!` in parallel.

That is looks great by me, specially considering how far into the weeds the conversation goes when I try to be more precise xD I have committed this version of your original proposal.

[vtjnash]

Some doc comments, but otherwise LGTM

[KronosTheLate]

Bump

[KronosTheLate]

I would not find the changes made here in the 1.11 alpha release notes. Is further action required for this to make it into there?

[KristofferC]

(FWIW, I think this should have been / should be more descriptive. isfull made me think it was the opposite of issparse.)

[KronosTheLate]

(FWIW, I think this should have been / should be more descriptive. isfull made me think it was the opposite of issparse.)

Fair point. I expect that many people who regularly work with matrices, which are a lot of people, would feel the same. Importantly, people who use Julia are more likely to also be people who regularly work with matrices. So I expect this will be an issue for others as well.

I do however have to object. The opposite of full is empty, not sparse. Full/empty is a more natural dichotomy than full/sparse. The current name has the most natural meaning, without being so specific as to become hard to discover. Also, would the opposite of sparse not be dense? I may be wrong of course, but I feel quite certain that the name is fine.

[KristofferC]

Yeah, thinking about it some more, I guess isfull has a generic concept like isempty so this is probably fine.