What does ‘serial’ do?
On Supply
s, it is an informational method that is supposed to indicate whether there will never be any concurrent emit
on that Supply.
On HyperSeq
and RaceSeq
, it returns a serialized Seq
, so you could consider it the opposite of the hyper
and race
method.
In general, it appears to return itself, which seems to make sense from the HyperSeq
and RaceSeq
point of view.
And yes, these should be documented properly, so please create a documentation issue. Thank you!
In the doc example it does nothing. That is, if you remove it you get the same results:
my $b; # defaults to Any
say $b.^name; # OUTPUT: «Any»
my $breakfast = 'food';
$breakfast.say; # OUTPUT: «food»
More generally, I think you'd best ignore the serial
method other than to open a doc issue pointing to this SO if you'd like to improve the doc.
The serial
method does not appear to be in the official language
A search of the roast repo for "serial" yields zero matches.
Within Rakudo source code the method name serial
has been overloaded to have one of three meanings:
A boolean declaring whether a
Supply
sequence is always serial. Rakudo source examples: 1, 2. This looks to me like an internal method that doesn't need to be documented.A coercion of parallel sequence (hyper or race) to a serial version of the same sequence. This looks to me like an internal method that doesn't need to be documented.
A "no op" that returns its invocant. I suspect it would be best if it were not documented, at least until such time as its raison d'etre is clear; its official status viz-a-viz the spec (roast) is clear; and/or there's an attempt to systematically document which operations have the
is nodal
set on them.
None of the above seems to warrant ordinary users' attention or documentation.
The Any
class definition of a serial
method seems pointless
The Any
class serial
method returns self
, i.e. when called it is a no op.
I don't currently understand why there is an Any
class definition.
One possible point for it would be that there are .serial
calls made by internal code on instances of an unknown and generally unknowable class and there thus needs to be a default definition of serial
in the Any
class.
But a search of the rakudo repo for ".serial" suggests that calls are only made to supplies or hyper/race seqs.
That said, I note the is nodal
trait on the proto serial
declaration in Any
that immediately precedes the multi method serial
declaration. Perhaps that is the reason it's in Any
.
See also Arbitrary drift of methods to Mu
and Any
.
The documentation you quoted seems pointless
The definition and example seem to reflect someone's sense of humor. I applaud use of humor but in this case I suspect the best improvement would be to just remove the page you linked.