Yahoo! UI Library

async-queue  3.0.0

Yahoo! UI Library > async-queue > AsyncQueue
Search:
 
Filters

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. Otherwise false.

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: 10 (10ms between callbacks)
  • 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

_defExecFn

protected void _defExecFn ( e )
Default functionality for the "execute" event. Executes the callback function
Parameters:
e <Event> the event object

_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

_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

_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

_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.

_initEvents

protected void _initEvents ( )
Initializes the instance events.

_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.

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.

Events

complete

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

Classes

Events

Copyright © 2009 Yahoo! Inc. All rights reserved.