2018-02-12 16:01:20 +00:00
|
|
|
/**
|
|
|
|
* @author Richard Davey <rich@photonstorm.com>
|
2022-02-28 14:29:51 +00:00
|
|
|
* @copyright 2022 Photon Storm Ltd.
|
2019-05-10 15:15:04 +00:00
|
|
|
* @license {@link https://opensource.org/licenses/MIT|MIT License}
|
2018-02-12 16:01:20 +00:00
|
|
|
*/
|
|
|
|
|
2017-11-09 23:55:59 +00:00
|
|
|
var Class = require('../utils/Class');
|
2019-10-02 11:13:07 +00:00
|
|
|
var EventEmitter = require('eventemitter3');
|
|
|
|
var Events = require('./events');
|
2017-11-09 23:55:59 +00:00
|
|
|
|
2018-02-09 04:35:23 +00:00
|
|
|
/**
|
|
|
|
* @classdesc
|
2018-10-19 14:53:04 +00:00
|
|
|
* A Process Queue maintains three internal lists.
|
2020-08-09 16:55:09 +00:00
|
|
|
*
|
2018-10-19 14:53:04 +00:00
|
|
|
* The `pending` list is a selection of items which are due to be made 'active' in the next update.
|
|
|
|
* The `active` list is a selection of items which are considered active and should be updated.
|
|
|
|
* The `destroy` list is a selection of items that were active and are awaiting being destroyed in the next update.
|
|
|
|
*
|
2019-03-07 13:36:01 +00:00
|
|
|
* When new items are added to a Process Queue they are put in the pending list, rather than being added
|
2018-10-19 14:53:04 +00:00
|
|
|
* immediately the active list. Equally, items that are removed are put into the destroy list, rather than
|
|
|
|
* being destroyed immediately. This allows the Process Queue to carefully process each item at a specific, fixed
|
|
|
|
* time, rather than at the time of the request from the API.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
|
|
|
* @class ProcessQueue
|
2019-10-02 11:13:07 +00:00
|
|
|
* @extends Phaser.Events.EventEmitter
|
2018-10-10 09:49:13 +00:00
|
|
|
* @memberof Phaser.Structs
|
2018-02-09 04:35:23 +00:00
|
|
|
* @constructor
|
|
|
|
* @since 3.0.0
|
2018-03-27 13:59:49 +00:00
|
|
|
*
|
|
|
|
* @generic T
|
2018-02-09 04:35:23 +00:00
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
var ProcessQueue = new Class({
|
|
|
|
|
2019-10-02 11:13:07 +00:00
|
|
|
Extends: EventEmitter,
|
|
|
|
|
2017-11-09 23:55:59 +00:00
|
|
|
initialize:
|
|
|
|
|
|
|
|
function ProcessQueue ()
|
|
|
|
{
|
2019-10-02 11:13:07 +00:00
|
|
|
EventEmitter.call(this);
|
|
|
|
|
2018-02-09 04:35:23 +00:00
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* The `pending` list is a selection of items which are due to be made 'active' in the next update.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
2018-03-29 10:56:47 +00:00
|
|
|
* @genericUse {T[]} - [$type]
|
2018-03-27 13:59:49 +00:00
|
|
|
*
|
2018-02-09 04:35:23 +00:00
|
|
|
* @name Phaser.Structs.ProcessQueue#_pending
|
2018-03-23 15:54:12 +00:00
|
|
|
* @type {Array.<*>}
|
2018-02-09 04:35:23 +00:00
|
|
|
* @private
|
|
|
|
* @default []
|
|
|
|
* @since 3.0.0
|
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
this._pending = [];
|
2018-02-09 04:35:23 +00:00
|
|
|
|
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* The `active` list is a selection of items which are considered active and should be updated.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
2018-03-29 10:56:47 +00:00
|
|
|
* @genericUse {T[]} - [$type]
|
2018-03-27 13:59:49 +00:00
|
|
|
*
|
2018-02-09 04:35:23 +00:00
|
|
|
* @name Phaser.Structs.ProcessQueue#_active
|
2018-03-23 15:54:12 +00:00
|
|
|
* @type {Array.<*>}
|
2018-02-09 04:35:23 +00:00
|
|
|
* @private
|
|
|
|
* @default []
|
|
|
|
* @since 3.0.0
|
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
this._active = [];
|
2018-02-09 04:35:23 +00:00
|
|
|
|
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* The `destroy` list is a selection of items that were active and are awaiting being destroyed in the next update.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
2018-03-29 10:56:47 +00:00
|
|
|
* @genericUse {T[]} - [$type]
|
2018-03-27 13:59:49 +00:00
|
|
|
*
|
2018-02-09 04:35:23 +00:00
|
|
|
* @name Phaser.Structs.ProcessQueue#_destroy
|
2018-03-23 15:54:12 +00:00
|
|
|
* @type {Array.<*>}
|
2018-02-09 04:35:23 +00:00
|
|
|
* @private
|
|
|
|
* @default []
|
|
|
|
* @since 3.0.0
|
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
this._destroy = [];
|
|
|
|
|
2018-02-09 04:35:23 +00:00
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* The total number of items awaiting processing.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
|
|
|
* @name Phaser.Structs.ProcessQueue#_toProcess
|
2020-11-23 10:22:13 +00:00
|
|
|
* @type {number}
|
2018-02-09 04:35:23 +00:00
|
|
|
* @private
|
|
|
|
* @default 0
|
|
|
|
* @since 3.0.0
|
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
this._toProcess = 0;
|
2020-08-24 18:21:01 +00:00
|
|
|
|
|
|
|
/**
|
|
|
|
* If `true` only unique objects will be allowed in the queue.
|
|
|
|
*
|
|
|
|
* @name Phaser.Structs.ProcessQueue#checkQueue
|
|
|
|
* @type {boolean}
|
|
|
|
* @since 3.50.0
|
|
|
|
*/
|
|
|
|
this.checkQueue = false;
|
2017-11-09 23:55:59 +00:00
|
|
|
},
|
|
|
|
|
2022-06-07 15:43:56 +00:00
|
|
|
/**
|
|
|
|
* Checks the given item to see if it is already active within this Process Queue.
|
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#isActive
|
|
|
|
* @since 3.60.0
|
|
|
|
*
|
|
|
|
* @genericUse {T} - [item]
|
|
|
|
* @genericUse {Phaser.Structs.ProcessQueue.<T>} - [$return]
|
|
|
|
*
|
|
|
|
* @param {*} item - The item to check.
|
|
|
|
*
|
|
|
|
* @return {boolean} `true` if the item is active, otherwise `false`.
|
|
|
|
*/
|
|
|
|
isActive: function (item)
|
|
|
|
{
|
|
|
|
return (this._active.indexOf(item) > -1);
|
|
|
|
},
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Checks the given item to see if it is already pending addition to this Process Queue.
|
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#isPending
|
|
|
|
* @since 3.60.0
|
|
|
|
*
|
|
|
|
* @genericUse {T} - [item]
|
|
|
|
* @genericUse {Phaser.Structs.ProcessQueue.<T>} - [$return]
|
|
|
|
*
|
|
|
|
* @param {*} item - The item to check.
|
|
|
|
*
|
|
|
|
* @return {boolean} `true` if the item is pending insertion, otherwise `false`.
|
|
|
|
*/
|
|
|
|
isPending: function (item)
|
|
|
|
{
|
|
|
|
return (this._toProcess > 0 && this._pending.indexOf(item) > -1);
|
|
|
|
},
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Checks the given item to see if it is already pending destruction from this Process Queue.
|
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#isDestroying
|
|
|
|
* @since 3.60.0
|
|
|
|
*
|
|
|
|
* @genericUse {T} - [item]
|
|
|
|
* @genericUse {Phaser.Structs.ProcessQueue.<T>} - [$return]
|
|
|
|
*
|
|
|
|
* @param {*} item - The item to check.
|
|
|
|
*
|
|
|
|
* @return {boolean} `true` if the item is pending destruction, otherwise `false`.
|
|
|
|
*/
|
|
|
|
isDestroying: function (item)
|
|
|
|
{
|
|
|
|
return (this._destroy.indexOf(item) > -1);
|
|
|
|
},
|
|
|
|
|
2018-02-09 04:35:23 +00:00
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* Adds a new item to the Process Queue.
|
2020-08-09 16:55:09 +00:00
|
|
|
*
|
2018-10-19 14:53:04 +00:00
|
|
|
* The item is added to the pending list and made active in the next update.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#add
|
|
|
|
* @since 3.0.0
|
|
|
|
*
|
2018-03-29 10:56:47 +00:00
|
|
|
* @genericUse {T} - [item]
|
2018-03-30 12:43:58 +00:00
|
|
|
* @genericUse {Phaser.Structs.ProcessQueue.<T>} - [$return]
|
2018-03-27 13:59:49 +00:00
|
|
|
*
|
2018-10-19 14:53:04 +00:00
|
|
|
* @param {*} item - The item to add to the queue.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
2019-10-02 11:13:07 +00:00
|
|
|
* @return {*} The item that was added.
|
2018-02-09 04:35:23 +00:00
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
add: function (item)
|
|
|
|
{
|
2022-11-10 22:14:18 +00:00
|
|
|
// Don't add if already active or pending, but DO add if active AND in the destroy list
|
|
|
|
if (this.checkQueue && (this.isActive() && !this.isDestroying()) || this.isPending())
|
2022-06-07 15:43:56 +00:00
|
|
|
{
|
|
|
|
return item;
|
|
|
|
}
|
|
|
|
|
2017-11-09 23:55:59 +00:00
|
|
|
this._pending.push(item);
|
|
|
|
|
|
|
|
this._toProcess++;
|
|
|
|
|
2019-10-02 11:13:07 +00:00
|
|
|
return item;
|
2017-11-09 23:55:59 +00:00
|
|
|
},
|
|
|
|
|
2018-02-09 04:35:23 +00:00
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* Removes an item from the Process Queue.
|
2020-08-09 16:55:09 +00:00
|
|
|
*
|
2022-06-07 15:43:56 +00:00
|
|
|
* The item is added to the 'destroy' list and is fully removed in the next update.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#remove
|
|
|
|
* @since 3.0.0
|
|
|
|
*
|
2018-03-29 10:56:47 +00:00
|
|
|
* @genericUse {T} - [item]
|
2018-03-30 12:43:58 +00:00
|
|
|
* @genericUse {Phaser.Structs.ProcessQueue.<T>} - [$return]
|
2018-03-27 13:59:49 +00:00
|
|
|
*
|
2018-10-19 14:53:04 +00:00
|
|
|
* @param {*} item - The item to be removed from the queue.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
2019-10-02 11:13:07 +00:00
|
|
|
* @return {*} The item that was removed.
|
2018-02-09 04:35:23 +00:00
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
remove: function (item)
|
|
|
|
{
|
2022-06-07 15:43:56 +00:00
|
|
|
// Check if it's in the _pending list
|
|
|
|
if (this.isPending(item))
|
|
|
|
{
|
|
|
|
var pending = this._pending;
|
2017-11-09 23:55:59 +00:00
|
|
|
|
2022-06-07 15:43:56 +00:00
|
|
|
var idx = pending.indexOf(item);
|
|
|
|
|
|
|
|
if (idx !== -1)
|
|
|
|
{
|
|
|
|
// Remove directly, no need to wait for an update loop
|
|
|
|
pending.splice(idx, 1);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
else if (this.isActive(item))
|
|
|
|
{
|
|
|
|
// Item is actively running? Queue it for deletion
|
|
|
|
this._destroy.push(item);
|
|
|
|
|
|
|
|
this._toProcess++;
|
|
|
|
}
|
|
|
|
|
|
|
|
// If neither of the above conditions pass, then the item is either already in the destroy list,
|
|
|
|
// or isn't pending or active, so cannot be removed anyway
|
2017-11-09 23:55:59 +00:00
|
|
|
|
2019-10-02 11:13:07 +00:00
|
|
|
return item;
|
|
|
|
},
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Removes all active items from this Process Queue.
|
2020-08-09 16:55:09 +00:00
|
|
|
*
|
2019-10-02 11:13:07 +00:00
|
|
|
* All the items are marked as 'pending destroy' and fully removed in the next update.
|
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#removeAll
|
|
|
|
* @since 3.20.0
|
|
|
|
*
|
|
|
|
* @return {this} This Process Queue object.
|
|
|
|
*/
|
|
|
|
removeAll: function ()
|
|
|
|
{
|
|
|
|
var list = this._active;
|
|
|
|
var destroy = this._destroy;
|
|
|
|
var i = list.length;
|
|
|
|
|
|
|
|
while (i--)
|
|
|
|
{
|
|
|
|
destroy.push(list[i]);
|
|
|
|
|
|
|
|
this._toProcess++;
|
|
|
|
}
|
|
|
|
|
2017-11-09 23:55:59 +00:00
|
|
|
return this;
|
|
|
|
},
|
|
|
|
|
2018-02-09 04:35:23 +00:00
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* Update this queue. First it will process any items awaiting destruction, and remove them.
|
2020-08-09 16:55:09 +00:00
|
|
|
*
|
2018-10-19 14:53:04 +00:00
|
|
|
* Then it will check to see if there are any items pending insertion, and move them to an
|
|
|
|
* active state. Finally, it will return a list of active items for further processing.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#update
|
|
|
|
* @since 3.0.0
|
|
|
|
*
|
2018-03-29 10:56:47 +00:00
|
|
|
* @genericUse {T[]} - [$return]
|
2018-03-27 13:59:49 +00:00
|
|
|
*
|
2018-10-19 14:53:04 +00:00
|
|
|
* @return {Array.<*>} A list of active items.
|
2018-02-09 04:35:23 +00:00
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
update: function ()
|
|
|
|
{
|
|
|
|
if (this._toProcess === 0)
|
|
|
|
{
|
|
|
|
// Quick bail
|
|
|
|
return this._active;
|
|
|
|
}
|
|
|
|
|
|
|
|
var list = this._destroy;
|
|
|
|
var active = this._active;
|
|
|
|
var i;
|
|
|
|
var item;
|
|
|
|
|
|
|
|
// Clear the 'destroy' list
|
|
|
|
for (i = 0; i < list.length; i++)
|
|
|
|
{
|
|
|
|
item = list[i];
|
|
|
|
|
|
|
|
// Remove from the 'active' array
|
|
|
|
var idx = active.indexOf(item);
|
|
|
|
|
|
|
|
if (idx !== -1)
|
|
|
|
{
|
|
|
|
active.splice(idx, 1);
|
2019-10-02 11:13:07 +00:00
|
|
|
|
2020-08-09 16:55:09 +00:00
|
|
|
this.emit(Events.PROCESS_QUEUE_REMOVE, item);
|
2017-11-09 23:55:59 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
list.length = 0;
|
|
|
|
|
|
|
|
// Process the pending addition list
|
|
|
|
// This stops callbacks and out of sync events from populating the active array mid-way during an update
|
|
|
|
|
|
|
|
list = this._pending;
|
|
|
|
|
|
|
|
for (i = 0; i < list.length; i++)
|
|
|
|
{
|
|
|
|
item = list[i];
|
|
|
|
|
2020-08-24 18:21:01 +00:00
|
|
|
if (!this.checkQueue || (this.checkQueue && active.indexOf(item) === -1))
|
|
|
|
{
|
|
|
|
active.push(item);
|
2019-10-02 11:13:07 +00:00
|
|
|
|
2020-08-24 18:21:01 +00:00
|
|
|
this.emit(Events.PROCESS_QUEUE_ADD, item);
|
|
|
|
}
|
2017-11-09 23:55:59 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
list.length = 0;
|
|
|
|
|
|
|
|
this._toProcess = 0;
|
|
|
|
|
|
|
|
// The owner of this queue can now safely do whatever it needs to with the active list
|
2020-08-24 18:21:01 +00:00
|
|
|
return active;
|
2017-11-09 23:55:59 +00:00
|
|
|
},
|
|
|
|
|
2018-02-09 04:35:23 +00:00
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* Returns the current list of active items.
|
2020-08-09 16:55:09 +00:00
|
|
|
*
|
2019-10-02 11:13:07 +00:00
|
|
|
* This method returns a reference to the active list array, not a copy of it.
|
|
|
|
* Therefore, be careful to not modify this array outside of the ProcessQueue.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#getActive
|
|
|
|
* @since 3.0.0
|
|
|
|
*
|
2018-03-29 10:56:47 +00:00
|
|
|
* @genericUse {T[]} - [$return]
|
2018-03-27 13:59:49 +00:00
|
|
|
*
|
2018-10-19 14:53:04 +00:00
|
|
|
* @return {Array.<*>} A list of active items.
|
2018-02-09 04:35:23 +00:00
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
getActive: function ()
|
|
|
|
{
|
|
|
|
return this._active;
|
|
|
|
},
|
|
|
|
|
2019-10-02 11:13:07 +00:00
|
|
|
/**
|
|
|
|
* The number of entries in the active list.
|
|
|
|
*
|
|
|
|
* @name Phaser.Structs.ProcessQueue#length
|
2020-11-23 10:22:13 +00:00
|
|
|
* @type {number}
|
2019-10-02 11:13:07 +00:00
|
|
|
* @readonly
|
|
|
|
* @since 3.20.0
|
|
|
|
*/
|
|
|
|
length: {
|
|
|
|
|
|
|
|
get: function ()
|
|
|
|
{
|
|
|
|
return this._active.length;
|
|
|
|
}
|
|
|
|
|
|
|
|
},
|
|
|
|
|
2018-02-09 04:35:23 +00:00
|
|
|
/**
|
2018-10-19 14:53:04 +00:00
|
|
|
* Immediately destroys this process queue, clearing all of its internal arrays and resetting the process totals.
|
2018-02-09 04:35:23 +00:00
|
|
|
*
|
|
|
|
* @method Phaser.Structs.ProcessQueue#destroy
|
|
|
|
* @since 3.0.0
|
|
|
|
*/
|
2017-11-09 23:55:59 +00:00
|
|
|
destroy: function ()
|
|
|
|
{
|
2018-10-19 14:53:04 +00:00
|
|
|
this._toProcess = 0;
|
|
|
|
|
2017-11-09 23:55:59 +00:00
|
|
|
this._pending = [];
|
|
|
|
this._active = [];
|
|
|
|
this._destroy = [];
|
|
|
|
}
|
|
|
|
|
|
|
|
});
|
|
|
|
|
|
|
|
module.exports = ProcessQueue;
|