add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / util / Scheduler.js

/**\r
 * This class is used to bulk schedule a set of `Ext.util.Schedulable` items. The items\r
 * in the scheduler request time by calling their `schedule` method and when the time has\r
 * arrived its `react` method is called.\r
 *\r
 * The `react` methods are called in dependency order as determined by the sorting process.\r
 * The sorting process relies on each item to implement its own `sort` method.\r
 *\r
 * @private\r
 */\r
Ext.define('Ext.util.Scheduler', {\r
    mixins: [\r
        'Ext.mixin.Observable'\r
    ],\r
\r
    requires: [\r
        'Ext.util.Bag'\r
    ],\r
\r
    busyCounter: 0,\r
    lastBusyCounter: 0,\r
\r
    destroyed: false,\r
\r
    firing: null,\r
\r
    notifyIndex: -1,\r
\r
    nextId: 0,\r
\r
    orderedItems: null,\r
\r
    passes: 0,\r
\r
    scheduledCount: 0,\r
\r
    validIdRe: null,\r
\r
    config: {\r
        /**\r
         * @cfg {Number} cycleLimit\r
         * The maximum number of iterations to make over the items in one `notify` call.\r
         * This is used to prevent run away logic from looping infinitely. If this limit\r
         * is exceeded, an error is thrown (in development builds).\r
         * @private\r
         */\r
        cycleLimit: 5,\r
\r
        /**\r
         * @cfg {String/Function} preSort\r
         * If provided the `Schedulable` items will be pre-sorted by this function or\r
         * property value before the dependency sort.\r
         */\r
        preSort: null,\r
\r
        /**\r
         * @cfg {Number} tickDelay\r
         * The number of milliseconds to delay notification after the first `schedule`\r
         * request.\r
         */\r
        tickDelay: 5\r
    },\r
\r
    /**\r
     * @property {Boolean} suspendOnNotify\r
     * `true` to suspend layouts when the scheduler is triggering bindings. Setting this to `false`\r
     * may mean multiple layout runs on a single bind call which could affect performance.\r
     */\r
    suspendOnNotify: true,\r
\r
    constructor: function (config) {\r
        //<debug>\r
        if (Ext.util.Scheduler.instances) {\r
            Ext.util.Scheduler.instances.push(this);\r
        } else {\r
            Ext.util.Scheduler.instances = [ this ];\r
        }\r
        this.id = Ext.util.Scheduler.count = (Ext.util.Scheduler.count || 0) + 1;\r
        //</debug>\r
\r
        this.mixins.observable.constructor.call(this, config);\r
\r
        this.items = new Ext.util.Bag();\r
    },\r
\r
    destroy: function () {\r
        var me = this,\r
            timer = me.timer;\r
\r
        if (timer) {\r
            window.clearTimeout(timer);\r
            me.timer = null;\r
        }\r
        me.items.destroy();\r
        me.items = me.orderedItems = null;\r
\r
        me.callParent();\r
\r
        //<debug>\r
        Ext.Array.remove(Ext.util.Scheduler.instances, this);\r
        //</debug>\r
    },\r
\r
    /**\r
     * Adds an item to the scheduler. This is called internally by the `constructor` of\r
     * `{@link Ext.util.Schedulable}`.\r
     *\r
     * @param {Object} item The item to add.\r
     * @private\r
     * @since 5.0.0\r
     */\r
    add: function (item) {\r
        var me = this,\r
            items = me.items;\r
\r
        if (items === me.firing) {\r
            me.items = items = items.clone();\r
        }\r
\r
        item.id = item.id || ++me.nextId;\r
        item.scheduler = me;\r
        \r
        items.add(item);\r
\r
        if (!me.sortMap) {\r
            // If we are sorting we don't want to invalidate this... we will pick up the\r
            // new items just fine.\r
            me.orderedItems = null;\r
        }\r
    },\r
\r
    /**\r
     * Removes an item to the scheduler. This is called internally by the `destroy` method\r
     * of `{@link Ext.util.Schedulable}`.\r
     *\r
     * @param {Object} item The item to remove.\r
     * @private\r
     * @since 5.0.0\r
     */\r
    remove: function (item) {\r
        var me = this,\r
            items = me.items;\r
\r
        if (me.destroyed) {\r
            return;\r
        }\r
\r
        //<debug>\r
        if (me.sortMap) {\r
            Ext.raise('Items cannot be removed during sort');\r
        }\r
        //</debug>\r
\r
        if (items === me.firing) {\r
            me.items = items = items.clone();\r
        }\r
\r
        if (item.scheduled) {\r
            me.unscheduleItem(item);\r
            item.scheduled = false;\r
        }\r
\r
        items.remove(item);\r
\r
        me.orderedItems = null;\r
    },\r
\r
    /**\r
     * This method is called internally as needed to sort or resort the items in their\r
     * proper dependency order.\r
     *\r
     * @private\r
     * @since 5.0.0\r
     */\r
    sort: function () {\r
        var me = this,\r
            items = me.items,\r
            sortMap = {},\r
            preSort = me.getPreSort(),\r
            i, item;\r
\r
        me.orderedItems = [];\r
        me.sortMap = sortMap;\r
\r
        //<debug>\r
        me.sortStack = [];\r
        //</debug>\r
\r
        if (preSort) {\r
            items.sort(preSort);\r
        }\r
\r
        items = items.items; // grab the items array\r
\r
        // We reference items.length since items can be added during this loop\r
        for (i = 0; i < items.length; ++i) {\r
            item = items[i];\r
            if (!sortMap[item.id]) {\r
                me.sortItem(item);\r
            }\r
        }\r
\r
        me.sortMap = null;\r
\r
        //<debug>\r
        me.sortStack = null;\r
        //</debug>\r
    },\r
\r
    /**\r
     * Adds one item to the sorted items array. This can be called by the `sort` method of\r
     * `{@link Ext.util.Sortable sortable}` objects to add an item on which it depends.\r
     *\r
     * @param {Object} item The item to add.\r
     * @return {Ext.util.Scheduler} This instance.\r
     * @since 5.0.0\r
     */\r
    sortItem: function (item) {\r
        var me = this,\r
            sortMap = me.sortMap,\r
            orderedItems = me.orderedItems,\r
            itemId;\r
\r
        if (!item.scheduler) {\r
            me.add(item);\r
        }\r
\r
        itemId = item.id;\r
\r
        //<debug>\r
        if (item.scheduler !== me) {\r
            Ext.raise('Item ' + itemId + ' belongs to another Scheduler');\r
        }\r
\r
        me.sortStack.push(item);\r
\r
        if (sortMap[itemId] === 0) {\r
            for (var cycle = [], i = 0; i < me.sortStack.length; ++i) {\r
                cycle[i] = me.sortStack[i].getFullName();\r
            }\r
            Ext.raise('Dependency cycle detected: ' + cycle.join('\n --> '));\r
        }\r
        //</debug>\r
\r
        if (!(itemId in sortMap)) {\r
            // In production builds the above "if" will kick out the items that have\r
            // already been added (which it must) but also those that are being added\r
            // and have created a cycle (by virtue of the setting to 0). This check\r
            // should not be needed if cycles were all detected and removed in dev but\r
            // this is better than infinite recursion.\r
            sortMap[itemId] = 0;\r
\r
            if (!item.sort.$nullFn) {\r
                item.sort();\r
            }\r
\r
            sortMap[itemId] = 1;\r
\r
            item.order = me.orderedItems.length;\r
            orderedItems.push(item);\r
        }\r
\r
        //<debug>\r
        me.sortStack.pop();\r
        //</debug>\r
\r
        return me;\r
    },\r
\r
    /**\r
     * Adds multiple items to the sorted items array. This can be called by the `sort`\r
     * method of `{@link Ext.util.Sortable sortable}` objects to add items on which it\r
     * depends.\r
     *\r
     * @param {Object/Object[]} items The items to add. If this is an object, the values\r
     * are considered the items and the keys are ignored.\r
     * @return {Ext.util.Scheduler} This instance.\r
     * @since 5.0.0\r
     */\r
    sortItems: function (items) {\r
        var me = this,\r
            sortItem = me.sortItem;\r
\r
        if (items) {\r
            if (items instanceof Array) {\r
                Ext.each(items, sortItem, me);\r
            } else {\r
                Ext.Object.eachValue(items, sortItem, me);\r
            }\r
        }\r
\r
        return me;\r
    },\r
\r
    applyPreSort: function (preSort) {\r
        if (typeof preSort === 'function') {\r
            return preSort;\r
        }\r
\r
        var parts = preSort.split(','),\r
            direction = [],\r
            length = parts.length,\r
            c, i, s;\r
\r
        for (i = 0; i < length; ++i) {\r
            direction[i] = 1;\r
            s = parts[i];\r
\r
            if ((c = s.charAt(0)) === '-') {\r
                direction[i] = -1;\r
            } else if (c !== '+') {\r
                c = 0;\r
            }\r
\r
            if (c) {\r
                parts[i] = s.substring(1);\r
            }\r
        }\r
\r
        return function (lhs, rhs) {\r
            var ret = 0,\r
                i, prop, v1, v2;\r
\r
            for (i = 0; !ret && i < length; ++i) {\r
                prop = parts[i];\r
                v1 = lhs[prop];\r
                v2 = rhs[prop];\r
                ret = direction[i] * ((v1 < v2) ? -1 : ((v2 < v1) ? 1 : 0));\r
            }\r
\r
            return ret;\r
        };\r
    },\r
\r
    //-------------------------------------------------------------------------\r
    // Callback scheduling\r
    // <editor-fold>\r
\r
    /**\r
     * This method can be called to force the delivery of any scheduled items. This is\r
     * called automatically on a timer when items request service.\r
     *\r
     * @since 5.0.0\r
     */\r
    notify: function () {\r
        var me = this,\r
            timer = me.timer,\r
            cyclesLeft = me.getCycleLimit(),\r
            globalEvents = Ext.GlobalEvents,\r
            suspend = me.suspendOnNotify,\r
            busyCounter, i, item, len, queue, firedEvent;\r
\r
        if (timer) {\r
            window.clearTimeout(timer);\r
            me.timer = null;\r
        }\r
\r
        //<debug>\r
        if (me.firing) {\r
            Ext.raise('Notify cannot be called recursively');\r
        }\r
        //</debug>\r
\r
        if (suspend) {\r
            Ext.suspendLayouts();\r
        }\r
\r
        while (me.scheduledCount) {\r
            if (cyclesLeft) {\r
                --cyclesLeft;\r
            } else {\r
                me.firing = null;\r
                //<debug>\r
                if (me.onCycleLimitExceeded) {\r
                    me.onCycleLimitExceeded();\r
                }\r
                //</debug>\r
                break;\r
            }\r
\r
            if (!firedEvent) {\r
                firedEvent = true;\r
                if (globalEvents.hasListeners.beforebindnotify) {\r
                    globalEvents.fireEvent('beforebindnotify', me);\r
                }\r
            }\r
\r
            ++me.passes;\r
\r
            // We need to sort before we start firing because items can be added as we\r
            // loop.\r
            if (!(queue = me.orderedItems)) {\r
                me.sort();\r
                queue = me.orderedItems;\r
            }\r
\r
            len = queue.length;\r
            if (len) {\r
                me.firing = me.items;\r
\r
                for (i = 0; i < len; ++i) {\r
                    item = queue[i];\r
\r
                    if (item.scheduled) {\r
                        item.scheduled = false;\r
                        --me.scheduledCount;\r
                        me.notifyIndex = i;\r
\r
                        //Ext.log('React: ' + item.getFullName());\r
                        // This sequence allows the reaction to schedule items further\r
                        // down the queue without a second pass but also to schedule an\r
                        // item that is "upstream" or even itself.\r
                        item.react();\r
\r
                        if (!me.scheduledCount) {\r
                            break;\r
                        }\r
                    }\r
                }\r
            }\r
        }\r
\r
        me.firing = null;\r
        me.notifyIndex = -1;\r
\r
        if (suspend) {\r
            Ext.resumeLayouts(true);\r
        }\r
\r
        // The last thing we do is check for idle state transition (now that whatever\r
        // else that was queued up has been dispatched):\r
        if ((busyCounter = me.busyCounter) !== me.lastBusyCounter) {\r
            if (!(me.lastBusyCounter = busyCounter)) {\r
                // Since the counters are not equal, we were busy and are not anymore,\r
                // so we can fire the idle event:\r
                me.fireEvent('idle', me);\r
            }\r
        }\r
    },\r
\r
    /**\r
     * The method called by the timer. This cleans up the state and calls `notify`.\r
     * @private\r
     * @since 5.0.0\r
     */\r
    onTick: function () {\r
        this.timer = null;\r
        this.notify();\r
    },\r
\r
    /**\r
     * Called to indicate that an item needs to be scheduled. This should not be called\r
     * directly. Call the item's `{@link Ext.util.Schedulable#schedule schedule}` method\r
     * instead.\r
     * @param {Object} item\r
     * @private\r
     * @since 5.0.0\r
     */\r
    scheduleItem: function (item) {\r
        var me = this;\r
\r
        ++me.scheduledCount;\r
        //Ext.log('Schedule: ' + item.getFullName());\r
\r
        if (!me.timer && !me.firing) {\r
            me.scheduleTick();\r
        }\r
    },\r
\r
    /**\r
     * This method starts the timer that will execute the next `notify`.\r
     * @param {Object} item\r
     * @private\r
     * @since 5.0.0\r
     */\r
    scheduleTick: function () {\r
        var me = this;\r
\r
        if (!me.destroyed && !me.timer) {\r
            me.timer = Ext.Function.defer(me.onTick, me.getTickDelay(), me);\r
        }\r
    },\r
\r
    /**\r
     * Called to indicate that an item needs to be removed from the schedule. This should\r
     * not be called directly. Call the item's `{@link Ext.util.Schedulable#unschedule unschedule}`\r
     * method instead.\r
     * @param {Object} item\r
     * @private\r
     * @since 5.0.0\r
     */\r
    unscheduleItem: function (item) {\r
        if (this.scheduledCount) {\r
            --this.scheduledCount;\r
        }\r
    },\r
\r
    // </editor-fold>\r
\r
    //-------------------------------------------------------------------------\r
    // Busy/Idle state tracking\r
    // <editor-fold>\r
\r
    /**\r
     * This method should be called when items become busy or idle. These changes are\r
     * useful outside to do things like update modal masks or status indicators. The\r
     * changes are delivered as `busy` and `idle` events.\r
     *\r
     * @param {Number} adjustment Should be `1` or `-1` only to indicate transition to\r
     * busy state or from busy state, respectively.\r
     * @since 5.0.0\r
     */\r
    adjustBusy: function (adjustment) {\r
        var me = this,\r
            busyCounter = me.busyCounter + adjustment;\r
\r
        me.busyCounter = busyCounter;\r
\r
        if (busyCounter) {\r
            // If we are now busy but were not previously, fire the busy event immediately\r
            // and update lastBusyCounter.\r
            if (!me.lastBusyCounter) {\r
                me.lastBusyCounter = busyCounter;\r
                me.fireEvent('busy', me);\r
            }\r
        } else if (me.lastBusyCounter && !me.timer) {\r
            // If we are now not busy but were previously, defer this to make sure that\r
            // we don't quickly start with some other activity.\r
            me.scheduleTick();\r
        }\r
    },\r
\r
    /**\r
     * Returns `true` if this object contains one or more busy items.\r
     * @return {Boolean}\r
     * @since 5.0.0\r
     */\r
    isBusy: function () {\r
        return !this.isIdle();\r
    },\r
\r
    /**\r
     * Returns `true` if this object contains no busy items.\r
     * @return {Boolean}\r
     * @since 5.0.0\r
     */\r
    isIdle: function () {\r
        return !(this.busyCounter + this.lastBusyCounter);\r
    },\r
\r
    // </editor-fold>\r
\r
    debugHooks: {\r
        $enabled: false, // Disable by default\r
\r
        onCycleLimitExceeded: function () {\r
            Ext.raise('Exceeded cycleLimit ' + this.getCycleLimit());\r
        },\r
\r
        scheduleItem: function (item) {\r
            if (!item) {\r
                Ext.raise('scheduleItem: Invalid argument');\r
            }\r
            Ext.log('Schedule item: ' + item.getFullName() + ' - ' + (this.scheduledCount+1));\r
            if (item.order <= this.notifyIndex) {\r
                Ext.log.warn('Suboptimal order: ' + item.order + ' < ' + this.notifyIndex);\r
            }\r
            this.callParent([item]);\r
        },\r
\r
        unscheduleItem: function (item) {\r
            if (!this.scheduledCount) {\r
                Ext.raise('Invalid scheduleCount');\r
            }\r
            this.callParent([item]);\r
            Ext.log('Unschedule item: ' + item.getFullName() + ' - ' + this.scheduledCount);\r
        }\r
    }\r
});\r