mirror of
https://github.com/xfarrow/blink
synced 2025-06-27 09:03:02 +02:00
Change endpoint from persons to people
This commit is contained in:
xfarrow
237
backend/apis/nodejs/node_modules/asap/README.md
generated
vendored
Normal file
237
backend/apis/nodejs/node_modules/asap/README.md
generated
vendored
Normal file
@ -0,0 +1,237 @@
|
||||
# ASAP
|
||||
|
||||
[](https://travis-ci.org/kriskowal/asap)
|
||||
|
||||
Promise and asynchronous observer libraries, as well as hand-rolled callback
|
||||
programs and libraries, often need a mechanism to postpone the execution of a
|
||||
callback until the next available event.
|
||||
(See [Designing API’s for Asynchrony][Zalgo].)
|
||||
The `asap` function executes a task **as soon as possible** but not before it
|
||||
returns, waiting only for the completion of the current event and previously
|
||||
scheduled tasks.
|
||||
|
||||
```javascript
|
||||
asap(function () {
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
[Zalgo]: http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony
|
||||
|
||||
This CommonJS package provides an `asap` module that exports a function that
|
||||
executes a task function *as soon as possible*.
|
||||
|
||||
ASAP strives to schedule events to occur before yielding for IO, reflow,
|
||||
or redrawing.
|
||||
Each event receives an independent stack, with only platform code in parent
|
||||
frames and the events run in the order they are scheduled.
|
||||
|
||||
ASAP provides a fast event queue that will execute tasks until it is
|
||||
empty before yielding to the JavaScript engine's underlying event-loop.
|
||||
When a task gets added to a previously empty event queue, ASAP schedules a flush
|
||||
event, preferring for that event to occur before the JavaScript engine has an
|
||||
opportunity to perform IO tasks or rendering, thus making the first task and
|
||||
subsequent tasks semantically indistinguishable.
|
||||
ASAP uses a variety of techniques to preserve this invariant on different
|
||||
versions of browsers and Node.js.
|
||||
|
||||
By design, ASAP prevents input events from being handled until the task
|
||||
queue is empty.
|
||||
If the process is busy enough, this may cause incoming connection requests to be
|
||||
dropped, and may cause existing connections to inform the sender to reduce the
|
||||
transmission rate or stall.
|
||||
ASAP allows this on the theory that, if there is enough work to do, there is no
|
||||
sense in looking for trouble.
|
||||
As a consequence, ASAP can interfere with smooth animation.
|
||||
If your task should be tied to the rendering loop, consider using
|
||||
`requestAnimationFrame` instead.
|
||||
A long sequence of tasks can also effect the long running script dialog.
|
||||
If this is a problem, you may be able to use ASAP’s cousin `setImmediate` to
|
||||
break long processes into shorter intervals and periodically allow the browser
|
||||
to breathe.
|
||||
`setImmediate` will yield for IO, reflow, and repaint events.
|
||||
It also returns a handler and can be canceled.
|
||||
For a `setImmediate` shim, consider [YuzuJS setImmediate][setImmediate].
|
||||
|
||||
[setImmediate]: https://github.com/YuzuJS/setImmediate
|
||||
|
||||
Take care.
|
||||
ASAP can sustain infinite recursive calls without warning.
|
||||
It will not halt from a stack overflow, and it will not consume unbounded
|
||||
memory.
|
||||
This is behaviorally equivalent to an infinite loop.
|
||||
Just as with infinite loops, you can monitor a Node.js process for this behavior
|
||||
with a heart-beat signal.
|
||||
As with infinite loops, a very small amount of caution goes a long way to
|
||||
avoiding problems.
|
||||
|
||||
```javascript
|
||||
function loop() {
|
||||
asap(loop);
|
||||
}
|
||||
loop();
|
||||
```
|
||||
|
||||
In browsers, if a task throws an exception, it will not interrupt the flushing
|
||||
of high-priority tasks.
|
||||
The exception will be postponed to a later, low-priority event to avoid
|
||||
slow-downs.
|
||||
In Node.js, if a task throws an exception, ASAP will resume flushing only if—and
|
||||
only after—the error is handled by `domain.on("error")` or
|
||||
`process.on("uncaughtException")`.
|
||||
|
||||
## Raw ASAP
|
||||
|
||||
Checking for exceptions comes at a cost.
|
||||
The package also provides an `asap/raw` module that exports the underlying
|
||||
implementation which is faster but stalls if a task throws an exception.
|
||||
This internal version of the ASAP function does not check for errors.
|
||||
If a task does throw an error, it will stall the event queue unless you manually
|
||||
call `rawAsap.requestFlush()` before throwing the error, or any time after.
|
||||
|
||||
In Node.js, `asap/raw` also runs all tasks outside any domain.
|
||||
If you need a task to be bound to your domain, you will have to do it manually.
|
||||
|
||||
```js
|
||||
if (process.domain) {
|
||||
task = process.domain.bind(task);
|
||||
}
|
||||
rawAsap(task);
|
||||
```
|
||||
|
||||
## Tasks
|
||||
|
||||
A task may be any object that implements `call()`.
|
||||
A function will suffice, but closures tend not to be reusable and can cause
|
||||
garbage collector churn.
|
||||
Both `asap` and `rawAsap` accept task objects to give you the option of
|
||||
recycling task objects or using higher callable object abstractions.
|
||||
See the `asap` source for an illustration.
|
||||
|
||||
|
||||
## Compatibility
|
||||
|
||||
ASAP is tested on Node.js v0.10 and in a broad spectrum of web browsers.
|
||||
The following charts capture the browser test results for the most recent
|
||||
release.
|
||||
The first chart shows test results for ASAP running in the main window context.
|
||||
The second chart shows test results for ASAP running in a web worker context.
|
||||
Test results are inconclusive (grey) on browsers that do not support web
|
||||
workers.
|
||||
These data are captured automatically by [Continuous
|
||||
Integration][].
|
||||
|
||||
[Continuous Integration]: https://github.com/kriskowal/asap/blob/master/CONTRIBUTING.md
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Caveats
|
||||
|
||||
When a task is added to an empty event queue, it is not always possible to
|
||||
guarantee that the task queue will begin flushing immediately after the current
|
||||
event.
|
||||
However, once the task queue begins flushing, it will not yield until the queue
|
||||
is empty, even if the queue grows while executing tasks.
|
||||
|
||||
The following browsers allow the use of [DOM mutation observers][] to access
|
||||
the HTML [microtask queue][], and thus begin flushing ASAP's task queue
|
||||
immediately at the end of the current event loop turn, before any rendering or
|
||||
IO:
|
||||
|
||||
[microtask queue]: http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#microtask-queue
|
||||
[DOM mutation observers]: http://dom.spec.whatwg.org/#mutation-observers
|
||||
|
||||
- Android 4–4.3
|
||||
- Chrome 26–34
|
||||
- Firefox 14–29
|
||||
- Internet Explorer 11
|
||||
- iPad Safari 6–7.1
|
||||
- iPhone Safari 7–7.1
|
||||
- Safari 6–7
|
||||
|
||||
In the absense of mutation observers, there are a few browsers, and situations
|
||||
like web workers in some of the above browsers, where [message channels][]
|
||||
would be a useful way to avoid falling back to timers.
|
||||
Message channels give direct access to the HTML [task queue][], so the ASAP
|
||||
task queue would flush after any already queued rendering and IO tasks, but
|
||||
without having the minimum delay imposed by timers.
|
||||
However, among these browsers, Internet Explorer 10 and Safari do not reliably
|
||||
dispatch messages, so they are not worth the trouble to implement.
|
||||
|
||||
[message channels]: http://www.whatwg.org/specs/web-apps/current-work/multipage/web-messaging.html#message-channels
|
||||
[task queue]: http://www.whatwg.org/specs/web-apps/current-work/multipage/webappapis.html#concept-task
|
||||
|
||||
- Internet Explorer 10
|
||||
- Safair 5.0-1
|
||||
- Opera 11-12
|
||||
|
||||
In the absense of mutation observers, these browsers and the following browsers
|
||||
all fall back to using `setTimeout` and `setInterval` to ensure that a `flush`
|
||||
occurs.
|
||||
The implementation uses both and cancels whatever handler loses the race, since
|
||||
`setTimeout` tends to occasionally skip tasks in unisolated circumstances.
|
||||
Timers generally delay the flushing of ASAP's task queue for four milliseconds.
|
||||
|
||||
- Firefox 3–13
|
||||
- Internet Explorer 6–10
|
||||
- iPad Safari 4.3
|
||||
- Lynx 2.8.7
|
||||
|
||||
|
||||
## Heritage
|
||||
|
||||
ASAP has been factored out of the [Q][] asynchronous promise library.
|
||||
It originally had a naïve implementation in terms of `setTimeout`, but
|
||||
[Malte Ubl][NonBlocking] provided an insight that `postMessage` might be
|
||||
useful for creating a high-priority, no-delay event dispatch hack.
|
||||
Since then, Internet Explorer proposed and implemented `setImmediate`.
|
||||
Robert Katić began contributing to Q by measuring the performance of
|
||||
the internal implementation of `asap`, paying particular attention to
|
||||
error recovery.
|
||||
Domenic, Robert, and Kris Kowal collectively settled on the current strategy of
|
||||
unrolling the high-priority event queue internally regardless of what strategy
|
||||
we used to dispatch the potentially lower-priority flush event.
|
||||
Domenic went on to make ASAP cooperate with Node.js domains.
|
||||
|
||||
[Q]: https://github.com/kriskowal/q
|
||||
[NonBlocking]: http://www.nonblocking.io/2011/06/windownexttick.html
|
||||
|
||||
For further reading, Nicholas Zakas provided a thorough article on [The
|
||||
Case for setImmediate][NCZ].
|
||||
|
||||
[NCZ]: http://www.nczonline.net/blog/2013/07/09/the-case-for-setimmediate/
|
||||
|
||||
Ember’s RSVP promise implementation later [adopted][RSVP ASAP] the name ASAP but
|
||||
further developed the implentation.
|
||||
Particularly, The `MessagePort` implementation was abandoned due to interaction
|
||||
[problems with Mobile Internet Explorer][IE Problems] in favor of an
|
||||
implementation backed on the newer and more reliable DOM `MutationObserver`
|
||||
interface.
|
||||
These changes were back-ported into this library.
|
||||
|
||||
[IE Problems]: https://github.com/cujojs/when/issues/197
|
||||
[RSVP ASAP]: https://github.com/tildeio/rsvp.js/blob/cddf7232546a9cf858524b75cde6f9edf72620a7/lib/rsvp/asap.js
|
||||
|
||||
In addition, ASAP factored into `asap` and `asap/raw`, such that `asap` remained
|
||||
exception-safe, but `asap/raw` provided a tight kernel that could be used for
|
||||
tasks that guaranteed that they would not throw exceptions.
|
||||
This core is useful for promise implementations that capture thrown errors in
|
||||
rejected promises and do not need a second safety net.
|
||||
At the same time, the exception handling in `asap` was factored into separate
|
||||
implementations for Node.js and browsers, using the the [Browserify][Browser
|
||||
Config] `browser` property in `package.json` to instruct browser module loaders
|
||||
and bundlers, including [Browserify][], [Mr][], and [Mop][], to use the
|
||||
browser-only implementation.
|
||||
|
||||
[Browser Config]: https://gist.github.com/defunctzombie/4339901
|
||||
[Browserify]: https://github.com/substack/node-browserify
|
||||
[Mr]: https://github.com/montagejs/mr
|
||||
[Mop]: https://github.com/montagejs/mop
|
||||
|
||||
## License
|
||||
|
||||
Copyright 2009-2014 by Contributors
|
||||
MIT License (enclosed)
|
||||
|
||||
Reference in New Issue
Block a user