Skip to content
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

Documentation/Add 'close' events to fs.ReadStream, fs.WriteStream, etc per Issue #6484 #6499

Closed
wants to merge 8 commits into from
Closed

Documentation/Add 'close' events to fs.ReadStream, fs.WriteStream, etc per Issue #6484 #6499

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9d48b5d
Add 'close' events to fs.ReadStream and fs.WriteSTream
May 1, 2016
ff217a8
Add 'close' event to stream.Writable per Issue #6484
May 1, 2016
827dfcb
Add #### prefix to Event: 'close' and backticks to 'close' similar to…
May 1, 2016
57aa9e6
Add more specifics to 'close' events for fs.ReadStream and fs.WriteSt…
May 1, 2016
439df4b
Fix/Changed 'close' event from 'fs.ReadStream' to 'fs.WriteStream'
May 1, 2016
b2a0db1
wrapped long lines at 80 chars, reworded
May 2, 2016
bcc8bd2
including the 'close' event as optional
May 2, 2016
8cdf720
add 'close' event as optional in stream.Readable
May 2, 2016
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
8 changes: 8 additions & 0 deletions doc/api/fs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,10 @@ Stop watching for changes on the given `fs.FSWatcher`.

Emitted when the ReadStream's file is opened.

### Event: 'close'

Emitted when the ReadStream's underlying file descriptor has been closed. Comes from fs.close() method.
Copy link
Contributor

Choose a reason for hiding this comment

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

Can you add a "the" in front of fs.close(). Also, please put fs.close() in backticks.

Copy link
Member

@jasnell jasnell May 1, 2016 •
edited
Loading

Choose a reason for hiding this comment

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

Suggested rewording (note also the addition of the backticks )

Emitted when the `ReadStream`'s underlying file descriptor has been closed using `fs.close()`.

(same below for WriteStream also)

Copy link
Contributor

Choose a reason for hiding this comment

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

Is the note about fs.close() really that helpful/useful? Maybe we could just drop that part entirely?

Copy link
Member

Choose a reason for hiding this comment

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

I'm good with it either way

Copy link
Contributor

Choose a reason for hiding this comment

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

The reason I ask is because either way we're wording it makes it kind of sound like the end user is expected to call fs.close()/stream.close() to see this event.

Copy link
Member

Choose a reason for hiding this comment

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

I do not think 'close' is emitted only with fs.close(), or am I wrong?


### readStream.path

The path to the file the stream is reading from as specified in the first
Expand Down Expand Up @@ -238,6 +242,10 @@ on Unix systems, it never was.

Emitted when the WriteStream's file is opened.

### Event: 'close'

Emitted when the WriteStream's underlying file descriptor has been closed. Comes from fs.close() method.
Copy link
Contributor

Choose a reason for hiding this comment

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

Same comment here.

Copy link
Member

Choose a reason for hiding this comment

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

@nodejs/streams can we please check this? I thought 'close' was for Readable and 'finish' was for 'Writable'. However, in 'fs' we have 'close' for 'Writable' as well. I do not think custom stream events are that helpful in understanding, so maybe we might want to rationalize this (or document it in streams).


### writeStream.bytesWritten

The number of bytes written so far. Does not include data that is still queued
Expand Down
6 changes: 6 additions & 0 deletions doc/api/stream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -572,6 +572,12 @@ Examples of writable streams include:
* [TCP sockets][]
* [child process stdin][]
* [`process.stdout`][], [`process.stderr`][]

#### Event: 'close'

Emitted when the stream and any of its underlying resources (a file descriptor, for example) have been closed. The event indicates that no more events will be emitted, and no further computation will occur.
Copy link
Member

Choose a reason for hiding this comment

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

How does this differs from 'end'?
Should a user expect 'close' or 'end' to proceed? Which one happens first?

I will also move this block after 'end', meaning that 'end' is the preferred way of waiting for the end of a stream.

Copy link
Contributor Author

@jennabelle jennabelle May 2, 2016 •
edited
Loading

Choose a reason for hiding this comment

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

@mcollina

I hesitate to move the 'Event: 'close'' block to after the 'Event: 'end'' block because these events seem to be in alphabetical order for better user experience.

The difference between 'close' and 'end' events:

  1. 'close' event - Whatever it is tied to, for example a stream, it is done now. This event comes from the fs.close() method and is optional. Not all streams emit this event.
  2. 'end' event - Waits for the current data to finish buffering. means no more data will be emitted. This event is tied to the end() function on Streams.


Not all streams will emit the `'close'` event.
Copy link
Member

Choose a reason for hiding this comment

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

I will say this is an optional event for implementors.


#### Event: 'drain'

Expand Down