Class atropa.SerialActor

Version 20130220.
A polling class designed for executing long running processes that return nothing and have no callback parameter.
Defined in: <node_modules/atropa-SerialActor/src/atropa-SerialActor.js>.

Class Summary
Constructor Attributes	Constructor Name and Description
	atropa.SerialActor(actorName, actorFunction) A polling class designed for executing long running processes that return nothing and have no callback parameter.

Field Summary
Field Attributes	Field Name and Description
	actorFunction The function to execute when the SerialActor is free.
	blocked The state of the SerialActor.
	blockTimeoutValue The maximum time, in milliseconds, which the actor may be blocked for.
	interval Polling interval in milliseconds.
	intervalId The id of the interval set to poll the actor.
	name The name of this instance.
	timeouts Stores id's of currently running timeout functions used to free the actor if it has been blocked for too long.

Method Summary
Method Attributes	Method Name and Description
	action() The action function is called when the actor is polled and it's blocked state is false.
	block() Prevents the actor from executing it's actorFunction.
	blockTimeout() Called when the `blockTimeoutValue` has been reached.
	changeInterval(interval) Adjusts the polling interval after `start` has been called.
	free() Frees the actor so it may execute its actor function when next polled.
	start(interval) Starts polling the actor.
	stop() Stops polling the actor.

Class Detail

atropa.SerialActor(actorName, actorFunction)

A polling class designed for executing long running processes that return nothing and have no callback parameter.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

function dummyActor(){
    var that = this;
    console.log('actorFunction would execute');
    console.log('freeing ' + this.name + ' in 10000 ms');
    setTimeout(function(){that.free();}, 10000);
};
var actor = new atropa.SerialActor('dummy', dummyActor);
    // change the name of the actor from
    // dummy to awesome
actor.name = "awesome";
    // set the polling interval (milliseconds)
actor.interval = 3000;
    // set the blocking timeout value (milliseconds)
actor.blockTimeoutValue = 120000;
    // start polling
actor.start();
    // dynamically change the SerialActor
setTimeout(function(){
    // change the polling interval
    // while the SerialActor is running.
    actor.changeInterval(2000);
        // change the actor function
    actor.actorFunction = function() {
        console.log('new actorFunction executing');
        console.log('freeing ' + this.name + ' immediately');
        this.free();
    };
},10000);

Parameters:
{String} actorName: The name for the SerialActor instance.
{Function} actorFunction: The function to execute when the SerialActor is free. This function must call the free function when it is finished in order to allow the actor to continue.

Returns:: {atropa.SerialActor} Returns an atropa.SerialActor instance.

Field Detail

{Function} actorFunction

The function to execute when the SerialActor is free. This function must call the free function when it is finished in order to allow the actor to continue. Defaults to the dummyActor function.

dummyActor = function(){
    console.log('actorFunction would execute');
    console.log('freeing Serial Actor in 10000 ms');
    setTimeout(function(){that.free();}, 10000);
};

See:: atropa.SerialActor-dummyActor

Default Value:: dummyActor

{Boolean} blocked

The state of the SerialActor. If true, the actor will sleep. If false the actor will execute the actor function when next polled. Defaults to false.

Default Value:: false

{Number} blockTimeoutValue

The maximum time, in milliseconds, which the actor may be blocked for. After this duration has been reached the actor will be freed. Defaults to 60 seconds.

Default Value:: 60000

{Number} interval

Polling interval in milliseconds. This determines how frequently the actor function will try to execute. Defaults to 100 milliseconds.

Default Value:: 100

{Number} intervalId

The id of the interval set to poll the actor. You should not change this manually, use the start and stop functions instead. Defauls to undefined.

Default Value:: undefined

{String} name

The name of this instance. Defaults to "SerialActor"

Default Value:: "SerialActor"

{Array} timeouts

Stores id's of currently running timeout functions used to free the actor if it has been blocked for too long.

See:: atropa.SerialActor#blockTimeoutValue

Default Value:: []

Method Detail

action()

The action function is called when the actor is polled and it's blocked state is false. This method should not be set or called manually, set the actorFunction instead.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

See:: atropa.SerialActor#actorFunction

{Boolean} block()

Prevents the actor from executing it's actorFunction. This block will timeout once the blockTimeoutValue has been reached.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

function d() {
    console.log('doing stuff to things');
    this.free();
}

var actor = new atropa.SerialActor('dummy', d);
actor.interval = 2000;
actor.blockTimeoutValue = 5000;
actor.start();
// 5 seconds after starting the actor will be blocked.
// It will remain blocked until the block timeout is reached.
setTimeout(function() {
    console.log('blocking!!!');
    actor.block();
}, 5000);

Returns:: {Boolean} Returns the value of this instances blocked property.

See:: atropa.SerialActor#blocked

{Boolean} blockTimeout()

Called when the blockTimeoutValue has been reached. This frees the actor and removes the timeout reference from the timeouts array.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

Returns:: {Boolean} Returns the value of this instances blocked property.

See:: atropa.SerialActor#blocked

{Number} changeInterval(interval)

Adjusts the polling interval after start has been called.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

var actor = new atropa.SerialActor('dummy');
actor.start();
    // 5 seconds after starting the polling interval will be changed.
setTimeout(function(){
    actor.changeInterval(2000);
}, 5000);

Parameters:
{Number} interval: The new polling interval in milliseconds.

Returns:: {Number} Returns the value of this instance's intervalId property.

See:: atropa.SerialActor#intervalId

{Boolean} free()

Frees the actor so it may execute its actor function when next polled.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

function d() {
    console.log('doing stuff to things');
    this.free();
}

var actor = new atropa.SerialActor('dummy', d);
actor.interval = 2000;
actor.blockTimeoutValue = 50000;
actor.start();
actor.block();
// 5 seconds after starting the actor will be freed.
setTimeout(function() {
    actor.free();
}, 5000);

Returns:: {Boolean} Returns the value of this instances blocked property.

See:: atropa.SerialActor#blocked

{Number} start(interval)

Starts polling the actor.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

var actor = new atropa.SerialActor('dummy');
actor.start();

Parameters:
{Number} interval: Optional. The polling interval. Defaults to the value of this.interval

Returns:: {Number} Returns the value of this instance's intervalId property.

See:: atropa.SerialActor#interval; atropa.SerialActor#intervalId

stop()

Stops polling the actor. Note that the actor will be freed once the blockTimeoutValue has been reached. This will not restart the polling.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

var actor = new atropa.SerialActor('dummy');
actor.start();
    // 5 seconds after starting the actor will be stopped.
setTimeout(function(){
    actor.stop();
}, 5000);

See:: atropa.SerialActor#blocked; atropa.SerialActor#blockTimeoutValue

Classes

Class atropa.SerialActor