Skip to content

Commit ef55324

Browse files
committed
Do not use Promise in 'fs' module
1 parent 662fdfe commit ef55324

12 files changed

+402
-384
lines changed

doc/api.txt

Lines changed: 151 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -236,9 +236,6 @@ Events are represented by a camel-cased string. Here are some examples:
236236
Functions can be then be attached to objects, to be executed when an event
237237
is emitted. These functions are called _listeners_.
238238

239-
Some asynchronous file operations return an +EventEmitter+ called a
240-
_promise_. A promise emits just a single event when the operation is
241-
complete.
242239

243240
=== +events.EventEmitter+
244241

@@ -586,60 +583,96 @@ will be sent +"SIGTERM"+. See signal(7) for a list of available signals.
586583
== File System
587584

588585
File I/O is provided by simple wrappers around standard POSIX functions. To
589-
use this module do +require("fs")+. All the methods have a similar form.
590-
They return a promise (+events.Promise+). Example of deleting a file:
586+
use this module do +require("fs")+. All the methods have asynchornous and
587+
synchronous forms.
591588

592-
------------------------------------------------------------------------------
589+
The asynchronous form always take a completion callback as its last
590+
argument. The arguments passed to the completion callback depend on the
591+
method, but the first argument is always reserved for an exception. If the
592+
operation was completed successfully, then the first argument will be +null+
593+
or +undefined+.
594+
595+
Here is an example of the asynchornous version:
596+
597+
-------------------------------------------------------
593598
var fs = require("fs"),
594599
sys = require("sys");
595600
596-
var promise = fs.unlink("/tmp/hello");
597-
598-
promise.addCallback(function () {
601+
fs.unlink("/tmp/hello", function (err) {
602+
if (err) throw err;
599603
sys.puts("successfully deleted /tmp/hello");
600604
});
601-
------------------------------------------------------------------------------
605+
-------------------------------------------------------
606+
607+
Here is the synchronous version:
608+
609+
-------------------------------------------------------
610+
var fs = require("fs"),
611+
sys = require("sys");
612+
613+
fs.unlinkSync("/tmp/hello")
614+
sys.puts("successfully deleted /tmp/hello");
615+
-------------------------------------------------------
602616

603-
This is asynchornous, there is no guaranteed ordering. The following is
604-
prone to error
617+
With the asynchronous methods there is no guaranteed ordering. So the
618+
following is prone to error:
605619

606-
------------------------------------------------------------------------------
607-
fs.rename("/tmp/hello", "/tmp/world");
608-
fs.stat("/tmp/world").addCallback(function (stats) {
620+
------------------------------------------------------
621+
fs.rename("/tmp/hello", "/tmp/world", function (err) {
622+
if (err) throw err;
623+
sys.puts("renamed complete");
624+
});
625+
fs.stat("/tmp/world", function (err, stats) {
626+
if (err) throw err;
609627
sys.puts("stats: " + JSON.stringify(stats));
610628
});
611-
------------------------------------------------------------------------------
629+
------------------------------------------------------
612630

613631
It could be that +fs.stat+ is executed before +fs.rename+.
614-
The correct way to do this is to chain the promises.
632+
The correct way to do this is to chain the callbacks.
615633

616-
------------------------------------------------------------------------------
617-
fs.rename("/tmp/hello", "/tmp/world").addCallback(function () {
618-
fs.stat("/tmp/world").addCallback(function (stats) {
634+
------------------------------------------------------
635+
fs.rename("/tmp/hello", "/tmp/world", function (err) {
636+
if (err) throw err;
637+
fs.stat("/tmp/world", function (err, stats) {
638+
if (err) throw err;
619639
sys.puts("stats: " + JSON.stringify(stats));
620640
});
621641
});
622-
------------------------------------------------------------------------------
642+
------------------------------------------------------
643+
644+
In busy processes, the programmer is _strongly encouraged_ to use the
645+
asynchronous versions of these calls. The synchronous versions will block
646+
the entire process until they complete--halting all connections.
623647

624648

625-
+fs.rename(path1, path2)+ ::
626-
See rename(2).
627-
- on success: no parameters.
628-
- on error: no parameters.
649+
+fs.rename(path1, path2, callback)+ ::
650+
Asynchronous rename(2).
651+
No arguments other than a possible exception are given to the completion callback.
629652

630-
+fs.truncate(fd, len)+ ::
631-
See ftruncate(2).
632-
- on success: no parameters.
633-
- on error: no parameters.
653+
+fs.renameSync(path1, path2)+ ::
654+
Synchronous rename(2).
655+
656+
657+
+fs.truncate(fd, len, callback)+ ::
658+
Asynchronous ftruncate(2).
659+
No arguments other than a possible exception are given to the completion callback.
660+
661+
+fs.truncateSync(fd, len)+ ::
662+
Synchronous ftruncate(2).
663+
664+
665+
+fs.chmod(path, mode, callback)+ ::
666+
Asynchronous chmod(2).
667+
No arguments other than a possible exception are given to the completion callback.
668+
669+
+fs.chmodSync(path, mode)+ ::
670+
Synchronous chmod(2).
634671

635-
+fs.chmod(path, mode)+ ::
636-
See chmod(1)
637-
- on success: no parameters.
638-
- on error: no parameters.
639672

640-
+fs.stat(path)+ ::
641-
See stat(2).
642-
- on success: Returns +fs.Stats+ object. It looks like this:
673+
+fs.stat(path, callback)+ ::
674+
Asynchronous stat(2). The callback gets two arguments +(err, stats)+ where
675+
+stats+ is a +fs.Stats+ object. It looks like this:
643676
+
644677
---------------------------------
645678
{ dev: 2049
@@ -660,91 +693,116 @@ See stat(2).
660693
+
661694
See the +fs.Stats+ section below for more information.
662695

663-
- on error: no parameters.
696+
+fs.statSync(path)+ ::
697+
Synchronous stat(2). Returns an instance of +fs.Stats+.
664698

665699

666-
+fs.unlink(path)+ ::
667-
See unlink(2)
668-
- on success: no parameters.
669-
- on error: no parameters.
700+
+fs.unlink(path, callback)+ ::
701+
Asynchronous unlink(2).
702+
No arguments other than a possible exception are given to the completion callback.
670703

704+
+fs.unlinkSync(path)+ ::
705+
Synchronous unlink(2).
671706

672-
+fs.rmdir(path)+ ::
673-
See rmdir(2)
674-
- on success: no parameters.
675-
- on error: no parameters.
676707

708+
+fs.rmdir(path, callback)+ ::
709+
Asynchronous rmdir(2).
710+
No arguments other than a possible exception are given to the completion callback.
677711

678-
+fs.mkdir(path, mode)+ ::
679-
See mkdir(2)
680-
- on success: no parameters.
681-
- on error: no parameters.
712+
+fs.rmdirSync(path)+ ::
713+
Synchronous rmdir(2).
682714

683715

684-
+fs.readdir(path)+ ::
685-
Reads the contents of a directory.
686-
- on success: One argument, an array containing the names (strings) of the
687-
files in the directory (excluding "." and "..").
688-
- on error: no parameters.
716+
+fs.mkdir(path, mode, callback)+ ::
717+
Asynchronous mkdir(2).
718+
No arguments other than a possible exception are given to the completion callback.
689719

720+
+fs.mkdirSync(path, mode)+ ::
721+
Synchronous mkdir(2).
690722

691-
+fs.close(fd)+ ::
692-
See close(2)
693-
- on success: no parameters.
694-
- on error: no parameters.
695723

724+
+fs.readdir(path, callback)+ ::
725+
Asynchronous readdir(3). Reads the contents of a directory.
726+
The callback gets two arguments +(err, files)+ where +files+ is an array of
727+
the names of the files in the directory excluding +"."+ and +".."+.
696728

697-
+fs.open(path, flags, mode=0666)+::
698-
See open(2). The constants like +O_CREAT+ are defined at +process.O_CREAT+.
699-
Also you can use the strings "r", "r+", "w", "w+", "a", or "a+" as aliases
700-
to the common flag combinations.
701-
- on success: +fd+ is given as the parameter.
702-
- on error: no parameters.
703729

730+
+fs.close(fd, callback)+ ::
731+
Asynchronous close(2).
732+
No arguments other than a possible exception are given to the completion callback.
704733

705-
+fs.write(fd, data, position, encoding)+::
706-
Write data to the file specified by +fd+. +position+ refers to the offset
707-
from the beginning of the file where this data should be written. If
708-
+position+ is +null+, the data will be written at the current position.
709-
See pwrite(2).
710-
- on success: returns an integer +written+ which specifies how many _bytes_ were written.
711-
- on error: no parameters.
734+
+fs.closeSync(fd)+ ::
735+
Synchronous close(2).
712736

713-
+fs.read(fd, length, position, encoding)+::
714-
Read data from the file specified by +fd+.
715-
+
716-
+length+ is an integer specifying the number of
717-
bytes to read.
718-
+
719-
+position+ is an integer specifying where to begin
720-
reading from in the file.
721-
+
722-
- on success: returns +data, bytes_read+, what was read from the file.
723-
- on error: no parameters.
724737

725-
+fs.readFile(filename, encoding="utf8")+::
726-
Outputs the entire contents of a file. Example:
738+
+fs.open(path, flags, mode, callback)+::
739+
Asynchronous file open. See open(2). Flags can be "r", "r+", "w", "w+", "a",
740+
or "a+". The callback gets two arguments +(err, fd)+.
741+
742+
+fs.openSync(path, flags, mode)+::
743+
Synchronous open(2).
744+
745+
746+
+fs.write(fd, data, position, encoding, callback)+::
747+
Write data to the file specified by +fd+. +position+ refers to the offset
748+
from the beginning of the file where this data should be written. If
749+
+position+ is +null+, the data will be written at the current position.
750+
See pwrite(2).
751+
+
752+
The callback will be given two arguments +(err, written)+ where +written+
753+
specifies how many _bytes_ were written.
754+
755+
+fs.writeSync(fd, data, position, encoding)+::
756+
Synchronous version of +fs.write()+. Returns the number of bytes written.
757+
758+
759+
+fs.read(fd, length, position, encoding, callback)+::
760+
Read data from the file specified by +fd+.
761+
+
762+
+length+ is an integer specifying the number of
763+
bytes to read.
764+
+
765+
+position+ is an integer specifying where to begin
766+
reading from in the file.
767+
+
768+
The callback is given three arguments, +(err, data, bytesRead)+ where +data+
769+
is a string--what was read--and +bytesRead+ is the number of bytes read.
770+
771+
+fs.readSync(fd, length, position, encoding)+::
772+
Synchronous version of +fs.read+. Returns an array +[data, bytesRead]+.
773+
774+
+fs.readFile(filename, encoding="utf8", callback)+::
775+
Asynchronously reads the entire contents of a file. Example:
727776
+
728777
--------------------------------
729-
fs.readFile("/etc/passwd").addCallback(function (content) {
778+
fs.readFile("/etc/passwd", function (err, data) {
779+
if (err) throw err;
730780
sys.puts(content);
731781
});
732782
--------------------------------
733783
+
734-
- on success: returns +data+, what was read from the file.
735-
- on error: no parameters.
784+
The callback is passed two arguments +(err, data)+, where +data+ is the
785+
contents of the file.
786+
787+
+fs.readFileSync(filename, encoding="utf8")+::
788+
Synchronous version of +fs.readFile+. Returns the contents of the
789+
+filename+.
790+
736791

737-
+fs.writeFile(filename, data, encoding="utf8")+::
738-
Writes data to a file. Example:
792+
+fs.writeFile(filename, data, encoding="utf8", callback)+::
793+
Asynchronously writes data to a file. Example:
739794
+
740795
--------------------------------
741-
fs.writeFile("message.txt", "Hello Node").addCallback(function () {
796+
fs.writeFile("message.txt", "Hello Node", function (err) {
797+
if (err) throw err;
742798
sys.puts("It's saved!");
743799
});
744800
--------------------------------
745-
+
746-
- on success: no parameters.
747-
- on error: no parameters.
801+
802+
+fs.writeFileSync(filename, data, encoding="utf8")+::
803+
The synchronous version of +fs.writeFile+.
804+
805+
748806

749807
=== +fs.Stats+
750808

0 commit comments

Comments
 (0)