Skip to content

Clean-up, modernize, and add examples for $| and autoflush #23147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: blead
Choose a base branch
from
Open

Clean-up, modernize, and add examples for $| and autoflush #23147

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5df2817
Clean-up, modernize, and add examples for `$|` and autoflush
scottchiefbaker Mar 21, 2025
b911e24
Clarify that it targets `C<$|>`
scottchiefbaker Mar 21, 2025
3e2e382
Remove example for setting autoflush to zero
scottchiefbaker Mar 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 31 additions & 10 deletions pod/perlvar.pod
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1828,19 +1828,40 @@ Also, it's just like C<$/>, but it's what you get "back" from Perl.
X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>

If set to nonzero, forces a flush right away and after every write or
print on the currently selected output channel. Default is 0
(regardless of whether the channel is really buffered by the system or
not; C<$|> tells you only whether you've asked Perl explicitly to
flush after each write). STDOUT will typically be line buffered if
output is to the terminal and block buffered otherwise. Setting this
variable is useful primarily when you are outputting to a pipe or
socket, such as when you are running a Perl program under B<rsh> and
want to see the output as it's happening. This has no effect on input
buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
how to select the output channel. See also L<IO::Handle>.
print on the currently selected output channel. The default is 0.

C<STDOUT> will typically be line buffered if output is to the terminal
and block buffered otherwise. Setting this variable is useful
primarily when you are outputting to a pipe or socket. This would
come into play when you are writing to a pipe and want to see the
output "live" with no buffering.

B<Examples:>

$| = 1; # Set autoflush for current channel
$is_buf = $|; # Get the current autoflush status

STDOUT->autoflush(1); # Enable autoflush for STDOUT
STDERR->autoflush(0); # Disable autoflush for STDERR

B<Warning:> C<$|> tells you only if you have asked Perl explicitly to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't exactly what the previous comment was saying. It is saying that the channel may be buffered or not, if it is not buffered already then autoflush won't have any effect but it still defaults to 0.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was worded weird originally which is why I tried to clean it up. I'm not sure what the correct less-wordy verbiage should be?

$| tells you only if you have asked Perl explicitly to flush after each write. It is still possible the channel may be buffered by the system.

"Warning: External to Perl, the system may buffer a channel. If the system is not buffering a channel, then setting autoflush will not have any effect." ??

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think rather than a warning, this statement is meant to be informational: the $|/autoflush setting always defaults to 0, and only indicates whether Perl flushes after each write, it does not indicate whether the channel is buffered by the system thus requiring flushing.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps it would be better to have this information in the same place where it discusses the usual buffering of STDOUT since this is the property it's describing and not the autoflush behavior itself. And add that STDERR is typically unbuffered (but this may be system dependent, I am only familiar with Linux behavior).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also I was not being precise in saying autoflush won't have any effect on an unbuffered stream; Perl will still flush the handle after each write, it just won't make a difference because it wasn't being buffered anyway.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The more I re-read this the more I think it was just informational. Personally I didn't think about the system buffering a channel, so knowing that setting autoflush in Perl may not always do what you want seems appropriate to me.

I think my wording here is ok-ish?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current wording in the commit is not useful information. The only reason to turn on autoflush is because the channel may be buffered.

flush after each write. It is still possible the channel may be buffered
by the system.

Mnemonic: when you want your pipes to be piping hot.

B<See also:>

=over

=item * L<perlfunc/select> to pick the output channel.

=item * L<IO::Handle> for more fine grained IO control.

=item * L<perlfunc/getc> for information on I<input> buffering.

=back

=item ${^LAST_FH}
X<${^LAST_FH}>

Expand Down
Loading