Skip to content

Commit

Permalink
[DOCS release] Update code samples for runloop functions
Browse files Browse the repository at this point in the history
  • Loading branch information
@locks
locks committed Dec 13, 2017
1 parent 9536e13 commit 9490bfe
Showing 1 changed file with 82 additions and 44 deletions.
126 changes: 82 additions & 44 deletions packages/ember-metal/lib/run_loop.js
View file
Expand Up @@ -46,6 +46,8 @@ const backburner = new Backburner(['sync', 'actions', 'destroy'], {
call.
```javascript
import { run } from '@ember/runloop';
run(function() {
// code to be executed within a RunLoop
});
Expand Down Expand Up @@ -76,17 +78,22 @@ export default function run() {
If invoked when not within a run loop:
```javascript
run.join(function() {
import { join } from '@ember/runloop';
join(function() {
// creates a new run-loop
});
```
Alternatively, if called within an existing run loop:
```javascript
import { run, join } from '@ember/runloop';
run(function() {
// creates a new run-loop
run.join(function() {
join(function() {
// joins with the existing run-loop, and queues for invocation on
// the existing run-loops action queue.
});
Expand Down Expand Up @@ -115,7 +122,7 @@ run.join = function() {
makes this method a great way to asynchronously integrate third-party libraries
into your Ember application.
`run.bind` takes two main arguments, the desired context and the function to
`bind` takes two main arguments, the desired context and the function to
invoke in that context. Any additional arguments will be supplied as arguments
to the function that is passed in.
Expand All @@ -127,10 +134,11 @@ run.join = function() {
```app/components/rich-text-editor.js
import Component from '@ember/component';
import { on } from '@ember/object/evented';
import { bind } from '@ember/runloop';
export default Component.extend({
initializeTinyMCE: Ember.on('didInsertElement', function() {
initializeTinyMCE: on('didInsertElement', function() {
tinymce.init({
selector: '#' + this.$().prop('id'),
setup: Ember.run.bind(this, this.setupEditor)
Expand Down Expand Up @@ -182,9 +190,11 @@ run.queues = backburner.queueNames;
a lower-level way to use a RunLoop instead of using `run()`.
```javascript
run.begin();
import { begin, end } from '@ember/runloop';
begin();
// code to be executed within a RunLoop
run.end();
end();
```
@method begin
Expand All @@ -203,9 +213,11 @@ run.begin = function() {
to use a RunLoop instead of using `run()`.
```javascript
run.begin();
import { begin, end } from '@ember/runloop';
begin();
// code to be executed within a RunLoop
run.end();
end();
```
@method end
Expand Down Expand Up @@ -241,12 +253,14 @@ run.end = function() {
the `run.queues` property.
```javascript
run.schedule('sync', this, function() {
import { schedule } from '@ember/runloop';
schedule('sync', this, function() {
// this will be executed in the first RunLoop queue, when bindings are synced
console.log('scheduled on sync queue');
});
run.schedule('actions', this, function() {
schedule('actions', this, function() {
// this will be executed in the 'actions' queue, after bindings have synced.
console.log('scheduled on actions queue');
});
Expand Down Expand Up @@ -326,7 +340,9 @@ run.sync = function() {
together, which is often more efficient than using a real setTimeout.
```javascript
run.later(myContext, function() {
import { later } from '@ember/runloop';
later(myContext, function() {
// code here will execute within a RunLoop in about 500ms with this == myContext
}, 500);
```
Expand Down Expand Up @@ -382,13 +398,15 @@ run.once = function(...args) {
calls.
```javascript
import { run, scheduleOnce } from '@ember/runloop';
function sayHi() {
console.log('hi');
}
run(function() {
run.scheduleOnce('afterRender', myContext, sayHi);
run.scheduleOnce('afterRender', myContext, sayHi);
scheduleOnce('afterRender', myContext, sayHi);
scheduleOnce('afterRender', myContext, sayHi);
// sayHi will only be executed once, in the afterRender queue of the RunLoop
});
```
Expand All @@ -402,7 +420,7 @@ run.once = function(...args) {
}
function scheduleIt() {
run.scheduleOnce('actions', myContext, log);
scheduleOnce('actions', myContext, log);
}
scheduleIt();
Expand All @@ -412,8 +430,10 @@ run.once = function(...args) {
But this other case will schedule the function multiple times:
```javascript
import { scheduleOnce } from '@ember/runloop';
function scheduleIt() {
run.scheduleOnce('actions', myContext, function() {
scheduleOnce('actions', myContext, function() {
console.log('Closure');
});
}
Expand Down Expand Up @@ -455,7 +475,9 @@ run.scheduleOnce = function(/*queue, target, method*/) {
`run.later` with a wait time of 1ms.
```javascript
run.next(myContext, function() {
import { next } from '@ember/runloop';
next(myContext, function() {
// code to be executed in the next run loop,
// which will be scheduled after the current one
});
Expand All @@ -477,11 +499,12 @@ run.scheduleOnce = function(/*queue, target, method*/) {
```app/components/my-component.js
import Component from '@ember/component';
import { scheduleOnce } from '@ember/runloop';
export Component.extend({
didInsertElement() {
this._super(...arguments);
run.scheduleOnce('afterRender', this, 'processChildElements');
scheduleOnce('afterRender', this, 'processChildElements');
},
processChildElements() {
Expand Down Expand Up @@ -522,53 +545,63 @@ run.next = function(...args) {
};

/**
Cancels a scheduled item. Must be a value returned by `run.later()`,
`run.once()`, `run.scheduleOnce()`, `run.next()`, `run.debounce()`, or
`run.throttle()`.
Cancels a scheduled item. Must be a value returned by `later()`,
`once()`, `scheduleOnce()`, `next()`, `debounce()`, or
`throttle()`.
```javascript
let runNext = run.next(myContext, function() {
import {
next,
cancel,
later,
scheduleOnce,
once,
throttle,
debounce
} from '@ember/runloop';
let runNext = next(myContext, function() {
// will not be executed
});
run.cancel(runNext);
cancel(runNext);
let runLater = run.later(myContext, function() {
let runLater = later(myContext, function() {
// will not be executed
}, 500);
run.cancel(runLater);
cancel(runLater);
let runScheduleOnce = run.scheduleOnce('afterRender', myContext, function() {
let runScheduleOnce = scheduleOnce('afterRender', myContext, function() {
// will not be executed
});
run.cancel(runScheduleOnce);
cancel(runScheduleOnce);
let runOnce = run.once(myContext, function() {
let runOnce = once(myContext, function() {
// will not be executed
});
run.cancel(runOnce);
cancel(runOnce);
let throttle = run.throttle(myContext, function() {
let throttle = throttle(myContext, function() {
// will not be executed
}, 1, false);
run.cancel(throttle);
cancel(throttle);
let debounce = run.debounce(myContext, function() {
let debounce = debounce(myContext, function() {
// will not be executed
}, 1);
run.cancel(debounce);
cancel(debounce);
let debounceImmediate = run.debounce(myContext, function() {
let debounceImmediate = debounce(myContext, function() {
// will be executed since we passed in true (immediate)
}, 100, true);
// the 100ms delay until this method can be called again will be canceled
run.cancel(debounceImmediate);
cancel(debounceImmediate);
```
@method cancel
Expand All @@ -594,16 +627,18 @@ run.cancel = function(timer) {
happen once scrolling has ceased.
```javascript
import { debounce } from '@ember/runloop';
function whoRan() {
console.log(this.name + ' ran.');
}
let myContext = { name: 'debounce' };
run.debounce(myContext, whoRan, 150);
debounce(myContext, whoRan, 150);
// less than 150ms passes
run.debounce(myContext, whoRan, 150);
debounce(myContext, whoRan, 150);
// 150ms passes
// whoRan is invoked with context myContext
Expand All @@ -617,26 +652,27 @@ run.cancel = function(timer) {
the method can be called again.
```javascript
import { debounce } from '@ember/runloop';
function whoRan() {
console.log(this.name + ' ran.');
}
let myContext = { name: 'debounce' };
run.debounce(myContext, whoRan, 150, true);
debounce(myContext, whoRan, 150, true);
// console logs 'debounce ran.' one time immediately.
// 100ms passes
run.debounce(myContext, whoRan, 150, true);
debounce(myContext, whoRan, 150, true);
// 150ms passes and nothing else is logged to the console and
// the debouncee is no longer being watched
run.debounce(myContext, whoRan, 150, true);
debounce(myContext, whoRan, 150, true);
// console logs 'debounce ran.' one time immediately.
// 150ms passes and nothing else is logged to the console and
// the debouncee is no longer being watched
```
@method debounce
Expand All @@ -662,24 +698,26 @@ run.debounce = function() {
the specified spacing period. The target method is called immediately.
```javascript
import { throttle } from '@ember/runloop';
function whoRan() {
console.log(this.name + ' ran.');
}
let myContext = { name: 'throttle' };
run.throttle(myContext, whoRan, 150);
throttle(myContext, whoRan, 150);
// whoRan is invoked with context myContext
// console logs 'throttle ran.'
// 50ms passes
run.throttle(myContext, whoRan, 150);
throttle(myContext, whoRan, 150);
// 50ms passes
run.throttle(myContext, whoRan, 150);
throttle(myContext, whoRan, 150);
// 150ms passes
run.throttle(myContext, whoRan, 150);
throttle(myContext, whoRan, 150);
// whoRan is invoked with context myContext
// console logs 'throttle ran.'
```
Expand Down

0 comments on commit 9490bfe

Please sign in to comment.