Spliterator flags as enum (was Initial java.util.Spliterator putback)

[Doug Lea]

On 03/29/13 12:05, Tim Peierls wrote:

> I'm not even trying to argue that the popular thinking is correct, just that it
> is popular enough to make it urgent that design decisions that run counter to it
> need to be explained carefully.

OK, but I'm not sure what to say here?

"You might have expected these to be defined in terms of enums and EnumSets,
but they weren't because we must ensure value-based propagation with
additional masking and unmasking across stream stages, and there is
no existing type to support this and we decided no to create one."

Suggestions for something less inappropriate for inclusion
in javadocs would be welcome. Unless we find some wording that rises
above the particulars, this seems to me  more like a FAQ issue than
something to put in javadocs though.

-Doug

>
> --tim
>
>
>
> On Fri, Mar 29, 2013 at 11:40 AM, Brian Goetz <brian.goetz at oracle.com
> <mailto:brian.goetz at oracle.com>> wrote:
>
>     Let's not lose sight of the fact that this is not a "for everyone" class
>     like ArrayList or Pattern.  This is low-level machinery for supporting
>     parallel operations.  If we've done our job correctly, the vast majority of
>     users will never see Spliterator.  Imagine this were part of the FJ
>     implementation (spliterators exist in 1:1 correspondence with FJTasks.)
>       Would you be making this same argument if this were ForkJoinTask?
>
>
>     On Mar 29, 2013, at 8:25 AM, Tim Peierls wrote:
>
>>     On Fri, Mar 29, 2013 at 10:53 AM, Doug Lea <dl at cs.oswego.edu
>>     <mailto:dl at cs.oswego.edu>> wrote:
>>
>>         But really, the painfulness quotient is equally important.
>>         We'd need to create immutableEnumSet class, and another class
>>         that can arbitrarily extend the Spliterator's enums with
>>         other control flags, all for the sake of arriving at an API
>>         that seems less clear and less easy to use than what we have.
>>
>>
>>     That API doesn't exist, so it's not really fair to say that it seems less
>>     clear and easy to use. As far as I can see in the common discussions, no
>>     one has seriously explored any alternatives.
>>
>>     The presence of such flags in a Java 8 API would (and should) raise a lot
>>     of eyebrows, because it goes against what people have been told for well
>>     over a decade. If it's adopted as is, there had better be a good
>>     explanation for doc readers of why alternatives were rejected. "We were
>>     comfortable with int flags and nothing else significantly better suggested
>>     itself" won't cut it. "We know int flags aren't great for an API, but we
>>     tried very hard to find better alternatives, to no avail" would (if it
>>     were true).
>>
>>     --tim
>
>