# Yahoo! UI Library

### queue 3.0.0b1

Yahoo! UI Library > queue > AsyncQueue
Search:
Filters Show Private Show Protected Show Deprecated

## Class AsyncQueue - extends EventTarget

A specialized queue class that supports scheduling callbacks to execute sequentially, iteratively, even asynchronously.

Callbacks can be function refs or objects with the following keys. Only the `fn` key is required.

- `fn` -- The callback function
- `context` -- The execution context for the callbackFn.
- `args` -- Arguments to pass to callbackFn.
- `timeout` -- Millisecond delay before executing callbackFn. (Applies to each iterative execution of callback)
- `iterations` -- Number of times to repeat the callback.
- `until` -- Repeat the callback until this function returns true. This setting trumps iterations.
- `autoContinue` -- Set to false to prevent the AsyncQueue from executing the next callback in the Queue after the callback completes.
- `id` -- Name that can be used to get, promote, get the indexOf, or delete this callback.

### Constructor

AsyncQueue `( callback* )`

Parameters:
  `callback* <Function|Object>` 0..n callbacks to seed the queue

### Properties

#### _running - `protected {Boolean|Object} true for synchronous callback execution, the return handle from Y.later for async callbacks`

Used to indicate the queue is currently executing a callback.

#### AsyncQueue.defaults - `static {Object}`

Static default values used to populate callback configuration properties. Preconfigured defaults include:

- `autoContinue`: `true`
- `iterations`: 1
- `timeout`: -1 (synchronous operation)
- `until`: (function to run until iterations <= 0)

#### defaults - `{Object}`

Callback defaults for this instance. Static defaults that are not overridden are also included.

### Methods

#### _defAddFn

`protected void _defAddFn ( e )`
Default functionality for the "add" event. Adds the callbacks in the event facade to the queue. Callbacks successfully added to the queue are present in the event's `added` property in the after phase.

Parameters:
  `e <Event>` the event object

Returns: `void`

#### _defExecFn

`protected void _defExecFn ( e )`
Default functionality for the "execute" event. Executes the callback function

Parameters:
  `e <Event>` the event object

Returns: `void`

#### _defPromoteFn

`protected void _defPromoteFn ( e )`

Default functionality for the "promote" event. Promotes the named callback to the head of the queue.

The event object will contain a property "callback", which holds the id of a callback or the callback object itself.

Parameters:
  `e <Event>` the custom event

Returns: `void`

#### _defRemoveFn

`protected void _defRemoveFn ( e )`

Default functionality for the "remove" event. Removes the callback from the queue.

The event object will contain a property "callback", which holds the id of a callback or the callback object itself.

Parameters:
  `e <Event>` the custom event

Returns: `void`

#### _defShiftFn

`protected void _defShiftFn ( e )`
Default functionality for the "shift" event. Shifts the callback stored in the event object's callback property from the queue if it is the first item.

Parameters:
  `e <Event>` The event object

Returns: `void`

#### _execute

`protected Boolean _execute ( callback )`
Handles the execution of callbacks. Returns a boolean indicating whether it is appropriate to continue running.

Parameters:
  `callback <Object>` the callback object to execute

Returns: `Boolean`
  whether the run loop should continue

#### _init

`protected void _init ( )`
Initializes the AsyncQueue instance properties and events.

Returns: `void`

#### _initEvents

`protected void _initEvents ( )`
Initializes the instance events.

Returns: `void`

#### _prepare

`protected Function _prepare ( callback )`
Creates a wrapper function to execute the callback using the aggregated configuration generated by combining the static AsyncQueue.defaults, the instance defaults, and the specified callback settings. The wrapper function is decorated with the callback configuration as properties for runtime modification.

Parameters:
  `callback <Object|Function>` the raw callback

Returns: `Function`
  a decorated function wrapper to execute the callback

#### _schedule

`protected Boolean _schedule ( callback )`
Schedules the execution of asynchronous callbacks.

Parameters:
  `callback <Object>` the callback object to execute

Returns: `Boolean`
  whether the run loop should continue

#### add

`AsyncQueue add ( callback* )`
Add any number of callbacks to the end of the queue. Callbacks may be provided as functions or objects.

Parameters:
  `callback* <Function|Object>` 0..n callbacks

Returns: `AsyncQueue`
  the AsyncQueue instance

Chainable: This method is chainable.

#### getCallback

`Object getCallback ( id )`
Retrieve a callback by its id. Useful to modify the configuration while the queue is running.

Parameters:
  `id <String>` the id assigned to the callback

Returns: `Object`
  the callback object

#### indexOf

`Number indexOf ( callback )`
Returns the current index of a callback. Pass in either the id or callback function from getCallback.

Parameters:
  `callback <String|Function>` the callback or its specified id

Returns: `Number`
  index of the callback or -1 if not found

#### isRunning

`Boolean isRunning ( )`
Determines if the queue is waiting for a callback to complete execution.

Returns: `Boolean`
  true if queue is waiting for a from any initiated transactions

#### next

`Function next ( )`
Returns the next callback needing execution. If a callback is configured to repeat via iterations or until, it will be returned until the completion criteria is met. When the queue is empty, null is returned.

Returns: `Function`
  the callback to execute

#### pause

`AsyncQueue pause ( )`
Pause the execution of the queue after the execution of the current callback completes. If called from code outside of a queued callback, clears the timeout for the pending callback. Paused queue can be restarted with q.run()

Returns: `AsyncQueue`
  the AsyncQueue instance

Chainable: This method is chainable.

#### promote

`AsyncQueue promote ( callback )`
Promotes the named callback to the top of the queue. If a callback is currently executing or looping (via until or iterations), the promotion is scheduled to occur after the current callback has completed.

Parameters:
  `callback <String|Object>` the callback object or a callback's id

Returns: `AsyncQueue`
  the AsyncQueue instance

Chainable: This method is chainable.

#### remove

`AsyncQueue remove ( callback )`
Removes the callback from the queue. If the queue is active, the removal is scheduled to occur after the current callback has completed.

Parameters:
  `callback <String|Object>` the callback object or a callback's id

Returns: `AsyncQueue`
  the AsyncQueue instance

Chainable: This method is chainable.

#### run

`AsyncQueue run ( )`
Sets the queue in motion. All queued callbacks will be executed in order unless pause() or stop() is called or if one of the callbacks is configured with autoContinue: false.

Returns: `AsyncQueue`
  the AsyncQueue instance

Chainable: This method is chainable.

#### size

`Number size ( )`
Returns the number of callbacks in the queue.

Returns: `Number`

#### stop

`AsyncQueue stop ( )`
Stop and clear the queue after the current execution of the current callback completes.

Returns: `AsyncQueue`
  the AsyncQueue instance

Chainable: This method is chainable.

#### Methods inherited from EventTarget:

`_getType, _parseType, addTarget, after, before, bubble, detach, detachAll, fire, getEvent, on, publish, removeTarget, subscribe, unsubscribe, unsubscribeAll`

### Events

#### complete

`complete ( )`
Event fired after the last queued callback is executed.

Copyright © 2009 Yahoo! Inc. All rights reserved.