Skip to content

Commit 6cbfcda

Browse files
trevnorristrevnorris
committed
src: move AsyncListener from process to tracing
The AsyncListener API has been moved into the "tracing" module in order to keep the process object free from unnecessary clutter. Signed-off-by: Timothy J Fontaine <[email protected]>
1 parent d9e1e4c commit 6cbfcda

24 files changed

Lines changed: 656 additions & 616 deletions

‎doc/api/process.markdown‎

Lines changed: 0 additions & 215 deletions
Original file line numberDiff line numberDiff line change
@@ -684,219 +684,4 @@ a diff reading, useful for benchmarks and measuring intervals:
684684
// benchmark took 1000000527 nanoseconds
685685
}, 1000);
686686

687-
688-
## Async Listeners
689-
690-
<!-- type=misc -->
691-
692-
Stability: 1 - Experimental
693-
694-
The `AsyncListener` API is the JavaScript interface for the `AsyncWrap`
695-
class which allows developers to be notified about key events in the
696-
lifetime of an asynchronous event. Node performs a lot of asynchronous
697-
events internally, and significant use of this API may have a
698-
**significant performance impact** on your application.
699-
700-
701-
## process.createAsyncListener(callbacksObj[, userData])
702-
703-
* `callbacksObj` {Object} Contains optional callbacks that will fire at
704-
specific times in the life cycle of the asynchronous event.
705-
* `userData` {Value} a value that will be passed to all callbacks.
706-
707-
Returns a constructed `AsyncListener` object.
708-
709-
To begin capturing asynchronous events pass either the `callbacksObj` or
710-
and existing `AsyncListener` instance to [`process.addAsyncListener()`][].
711-
The same `AsyncListener` instance can only be added once to the active
712-
queue, and subsequent attempts to add the instance will be ignored.
713-
714-
To stop capturing pass the `AsyncListener` instance to
715-
[`process.removeAsyncListener()`][]. This does _not_ mean the
716-
`AsyncListener` previously added will stop triggering callbacks. Once
717-
attached to an asynchronous event it will persist with the lifetime of the
718-
asynchronous call stack.
719-
720-
Explanation of function parameters:
721-
722-
723-
`callbacksObj`: An `Object` which may contain three optional fields:
724-
725-
* `create(userData)`: A `Function` called when an asynchronous
726-
event is instantiated. If a `Value` is returned then it will be attached
727-
to the event and overwrite any value that had been passed to
728-
`process.createAsyncListener()`'s `userData` argument. If an initial
729-
`userData` was passed when created, then `create()` will
730-
receive that as a function argument.
731-
732-
* `before(context, userData)`: A `Function` that is called immediately
733-
before the asynchronous callback is about to run. It will be passed both
734-
the `context` (i.e. `this`) of the calling function and the `userData`
735-
either returned from `create()` or passed during construction (if
736-
either occurred).
737-
738-
* `after(context, userData)`: A `Function` called immediately after
739-
the asynchronous event's callback has run. Note this will not be called
740-
if the callback throws and the error is not handled.
741-
742-
* `error(userData, error)`: A `Function` called if the event's
743-
callback threw. If this registered callback returns `true` then Node will
744-
assume the error has been properly handled and resume execution normally.
745-
When multiple `error()` callbacks have been registered only **one** of
746-
those callbacks needs to return `true` for `AsyncListener` to accept that
747-
the error has been handled, but all `error()` callbacks will always be run.
748-
749-
`userData`: A `Value` (i.e. anything) that will be, by default,
750-
attached to all new event instances. This will be overwritten if a `Value`
751-
is returned by `create()`.
752-
753-
Here is an example of overwriting the `userData`:
754-
755-
process.createAsyncListener({
756-
create: function listener(value) {
757-
// value === true
758-
return false;
759-
}, {
760-
before: function before(context, value) {
761-
// value === false
762-
}
763-
}, true);
764-
765-
**Note:** The [EventEmitter][], while used to emit status of an asynchronous
766-
event, is not itself asynchronous. So `create()` will not fire when
767-
an event is added, and `before`/`after` will not fire when emitted
768-
callbacks are called.
769-
770-
771-
## process.addAsyncListener(callbacksObj[, userData])
772-
## process.addAsyncListener(asyncListener)
773-
774-
Returns a constructed `AsyncListener` object and immediately adds it to
775-
the listening queue to begin capturing asynchronous events.
776-
777-
Function parameters can either be the same as
778-
[`process.createAsyncListener()`][], or a constructed `AsyncListener`
779-
object.
780-
781-
Example usage for capturing errors:
782-
783-
var fs = require('fs');
784-
785-
var cntr = 0;
786-
var key = process.addAsyncListener({
787-
create: function onCreate() {
788-
return { uid: cntr++ };
789-
},
790-
before: function onBefore(context, storage) {
791-
// Write directly to stdout or we'll enter a recursive loop
792-
fs.writeSync(1, 'uid: ' + storage.uid + ' is about to run\n');
793-
},
794-
after: function onAfter(context, storage) {
795-
fs.writeSync(1, 'uid: ' + storage.uid + ' ran\n');
796-
},
797-
error: function onError(storage, err) {
798-
// Handle known errors
799-
if (err.message === 'everything is fine') {
800-
fs.writeSync(1, 'handled error just threw:\n');
801-
fs.writeSync(1, err.stack + '\n');
802-
return true;
803-
}
804-
}
805-
});
806-
807-
process.nextTick(function() {
808-
throw new Error('everything is fine');
809-
});
810-
811-
// Output:
812-
// uid: 0 is about to run
813-
// handled error just threw:
814-
// Error: really, it's ok
815-
// at /tmp/test2.js:27:9
816-
// at process._tickCallback (node.js:583:11)
817-
// at Function.Module.runMain (module.js:492:11)
818-
// at startup (node.js:123:16)
819-
// at node.js:1012:3
820-
821-
## process.removeAsyncListener(asyncListener)
822-
823-
Removes the `AsyncListener` from the listening queue.
824-
825-
Removing the `AsyncListener` from the active queue does _not_ mean the
826-
`asyncListener` callbacks will cease to fire on the events they've been
827-
registered. Subsequently, any asynchronous events fired during the
828-
execution of a callback will also have the same `asyncListener` callbacks
829-
attached for future execution. For example:
830-
831-
var fs = require('fs');
832-
833-
var key = process.createAsyncListener({
834-
create: function asyncListener() {
835-
// Write directly to stdout or we'll enter a recursive loop
836-
fs.writeSync(1, 'You summoned me?\n');
837-
}
838-
});
839-
840-
// We want to begin capturing async events some time in the future.
841-
setTimeout(function() {
842-
process.addAsyncListener(key);
843-
844-
// Perform a few additional async events.
845-
setTimeout(function() {
846-
setImmediate(function() {
847-
process.nextTick(function() { });
848-
});
849-
});
850-
851-
// Removing the listener doesn't mean to stop capturing events that
852-
// have already been added.
853-
process.removeAsyncListener(key);
854-
}, 100);
855-
856-
// Output:
857-
// You summoned me?
858-
// You summoned me?
859-
// You summoned me?
860-
// You summoned me?
861-
862-
The fact that we logged 4 asynchronous events is an implementation detail
863-
of Node's [Timers][].
864-
865-
To stop capturing from a specific asynchronous event stack
866-
`process.removeAsyncListener()` must be called from within the call
867-
stack itself. For example:
868-
869-
var fs = require('fs');
870-
871-
var key = process.createAsyncListener({
872-
create: function asyncListener() {
873-
// Write directly to stdout or we'll enter a recursive loop
874-
fs.writeSync(1, 'You summoned me?\n');
875-
}
876-
});
877-
878-
// We want to begin capturing async events some time in the future.
879-
setTimeout(function() {
880-
process.addAsyncListener(key);
881-
882-
// Perform a few additional async events.
883-
setImmediate(function() {
884-
// Stop capturing from this call stack.
885-
process.removeAsyncListener(key);
886-
887-
process.nextTick(function() { });
888-
});
889-
}, 100);
890-
891-
// Output:
892-
// You summoned me?
893-
894-
The user must be explicit and always pass the `AsyncListener` they wish
895-
to remove. It is not possible to simply remove all listeners at once.
896-
897-
898687
[EventEmitter]: events.html#events_class_events_eventemitter
899-
[Timers]: timers.html
900-
[`process.createAsyncListener()`]: #process_process_createasynclistener_asynclistener_callbacksobj_storagevalue
901-
[`process.addAsyncListener()`]: #process_process_addasynclistener_asynclistener
902-
[`process.removeAsyncListener()`]: #process_process_removeasynclistener_asynclistener

0 commit comments

Comments
 (0)