Class waLongActionController

This controller helps to implement potentially long operations when it's impossible to avoid max execution time limit.

Each operation is identified by processId. It is possible to run several processes with different ids at the same time.

Only one instance of (descendant of) this class with given id can be a Runner at given time. Runner is an instance that performs actual work. Runner works until he's done or until he dies exceeding max execution time. Browser must request page again from time to time if old connection gets closed to resume the process.

While Runner is alive, all other possible instances will automatically become Messengers. Messenger don't do real work but can access (and give to user) some information about Runner's status.

It is possible to keep data that is guaranteed not to became corrupt regardless of when (or if) script fails. $this->data is a persistent array and $this->fd is a file descriptor with this guarantee. Only Runner has write access to this persistent data. All data in $this->data must be serializable.

For all methods of this class that are called inside a transaction:

If a script fails inside a transaction then all changes to $this->data and $this->fd file get reverted and are not visible inside subsequent transactions.
If transaction completes successfully then all changes to $this->data and $this->fd are visible to subsequent transactions.

Execution time for every function that runs inside a transaction must be reasonably small for this class to be able to keep it's guarantees. Reasonably small = no more than 10% of max execution time for each transaction.

Controller's entry point for this class expects a 'processId' get or post parameter. It then becomes available as $this->processId. If id is not given in request, a new process is started and $this->info() is responsible for returning id to user for subsequent operations. $this->newProcess indicates whether this Runner created the process (true) or not (false).

$this->finish() gets called when $this->isDone() return true. If $this->finish() return true, then process removes all its files and cannot be accessed again. Otherwise another instance can be called for this process to access the same result data and file.

Besides $this->fd and $this->data, $this->max_exec_time is also available for reading. It contains max execution time for this script (false if unknown).

waController

waLongActionController

Direct known subclasses

blogImportPluginBackendRunController, photosImportPluginRunController

Abstract
Package: wa-system\controller
Copyright: 2011 Webasyst LLC
Author: Webasyst LLC
Located at wa-system/controller/waLongActionController.class.php

Methods summary
`protected boolean`	# `preInit( )` Checks if it's ok to initialize a new process. Checks if it's ok to initialize a new process. Returns `boolean` true if initialization can start
`abstract protected`	# `init( )` Initializes new process. Runs inside a transaction ($this->data and $this->fd are accessible). Initializes new process. Runs inside a transaction ($this->data and $this->fd are accessible).
`abstract protected boolean`	# `isDone( )` Checks if there is any more work for $this->step() to do. Runs inside a transaction ($this->data and $this->fd are accessible). Checks if there is any more work for $this->step() to do. Runs inside a transaction ($this->data and $this->fd are accessible). $this->getStorage() session is already closed. Returns `boolean` whether all the work is done
`abstract protected boolean`	# `step( )` Performs a small piece of work. Runs inside a transaction ($this->data and $this->fd are accessible). Performs a small piece of work. Runs inside a transaction ($this->data and $this->fd are accessible). The longer it takes to complete one step, the more time it is possible to lose if script fails. The shorter, the more overhead there are because of copying $this->data and $this->fd after each step. So, it should be reasonably long and reasonably short at the same time. 5-10% of max execution time is recommended. $this->getStorage() session is already closed. Returns `boolean` false to end this Runner and call info(); true to continue.
`abstract protected boolean`	# `finish( mixed $filename )` Called when $this->isDone() is true $this->data is read-only, $this->fd is not available. Called when $this->isDone() is true $this->data is read-only, $this->fd is not available. $this->getStorage() session is already closed. Parameters `$filename` `mixed` $filename string full path to resulting file Returns `boolean` true to delete all process files; false to be able to access process again.
`protected`	# `restore( )` Called by a new Runner when the old one dies. Should be used to restore any non-persistent data for $this->step() if needed. Runs inside a transaction ($this->data and $this->fd are accessible). $this->getStorage() session is already closed. Called by a new Runner when the old one dies. Should be used to restore any non-persistent data for $this->step() if needed. Runs inside a transaction ($this->data and $this->fd are accessible). $this->getStorage() session is already closed.
`protected`	# `info( )` Called by a Messenger when the Runner is still alive, or when a Runner exited voluntarily, but isDone() is still false. Called by a Messenger when the Runner is still alive, or when a Runner exited voluntarily, but isDone() is still false. This function must send $this->processId to allow user to continue. $this->data is read-only. $this->fd is not available.
`public`	# `execute( )`
`private`	# `_cleanup( )` Close $this->_fd and remove all files we created Close $this->_fd and remove all files we created
`private`	# `_initDataStructures( )` Creates private files and $this->... data structures for new process. Initializes $this->_processId, $this->_data, $this->_fd, $this->_runner = true Called once when a process is created. Creates private files and $this->... data structures for new process. Initializes $this->_processId, $this->_data, $this->_fd, $this->_runner = true Called once when a process is created.
`private string`	# `_obtainLock( )` Checks if there's a Runner for $this->processId. If there is one then initializes $this->_data, $this->_runner = false If there are no Runner then initializes $this->_data, $this->_fd, $this->_runner = true\ Checks if there's a Runner for $this->processId. If there is one then initializes $this->_data, $this->_runner = false If there are no Runner then initializes $this->_data, $this->_fd, $this->_runner = true\ Returns `string` status of this instance: TYPE_RUNNER, TYPE_MESSENGER, or TYPE_NONE if data files not found. Throws `waException`
`private Array\|boolean`	# `unserializeData( mixed $fileContents )` Parameters `$fileContents` `mixed` $fileContents string data file contents Returns `Array\|boolean` Unserialized array or false on failure Throws `waException`
`private String`	# `serializeData( mixed $array )` Parameters `$array` `mixed` $array Array data to serialize Returns `String` serialized data Throws `waException`
`private`	# `_loadData( )` Loads data from files using filenames from $this->_files Makes sure both $this->_data and $this->_fd contain non-corrupt data, restoring it if needed. Loads data from files using filenames from $this->_files Makes sure both $this->_data and $this->_fd contain non-corrupt data, restoring it if needed.
`private`	# `_getFilenames( )` Return a new $this->_files structure using $this->processId Return a new $this->_files structure using $this->processId
`protected`	# `save( )` Saves output data chunk Saves output data chunk
`private`	# `_save( mixed $force = false, mixed $attempts = 3 )` Saves current persistent data. Saves current persistent data.
`private boolean`	# `_mainLock( string $filename, string $filename2 )` Our own robust file locking mechanism. Best we can afford still being compatible with everything. Never blocks, except on (damned) Windows in rare circumstances. Our own robust file locking mechanism. Best we can afford still being compatible with everything. Never blocks, except on (damned) Windows in rare circumstances. Parameters `$filename` `string` $filename `$filename2` `string` $filename2 Returns `boolean` true if lock is obtained, false otherwise Throws `waException`
`public &`	# `__get( mixed $field )`
`public`	# `__set( mixed $field, mixed $value )`
`private`	# `put( mixed $filename, mixed $data )`
`private`	# `get( mixed $filename )`
`public static`	# `shutdown( )`
`private`	# `initEnv( )`

Methods inherited from waController
`__call(), appSettings(), configPath(), getApp(), getAppId(), getConfig(), getPluginRoot(), getRequest(), getResponse(), getRights(), getStorage(), getUser(), getUserId(), log(), logAction(), preExecute(), redirect(), run(), storage()`

Constants summary
`string`	`TYPE_RUNNER`	`'runner'`	#
`string`	`TYPE_MESSENGER`	`'messenger'`	#
`string`	`TYPE_NONE`	`'no process'`	#

Properties summary
`private static waLongActionController`	`$instance`		#
`private integer`	`$_processId`	`0`	#
`private array`	`$_data`	`array( 'data' => array(), // actual source for $this->data for __get() and __set() 'avg_time' => 15, // average time in seconds between calls to $this->_save(), total_time/total_saves 'total_saves' => 0, 'total_time' => 0, 'heartbeat' => false, //timestamp of last save 'complete' => false, 'ready' => false, )`	#
`private resource`	`$_fd`	`null`	# actual source for $this->fd for __get() actual source for $this->fd for __get()
`private boolean`	`$_transaction`	`false`	#
`private boolean`	`$_runner`	`false`	#
`private boolean`	`$_newProcess`	`false`	#
`private mixed`	`$_max_exec_time`		#
`private mixed`	`$_chunk_time`		#
`private array`	`$_files`	`array( 'new' => array( 'data' => '', // file with $this->data serialized. 'file' => '', // $this->fd points here. File is locked by a live Runner permanently. ), 'old' => array( // A second pair of data files to ensure persistence. 'data' => '', 'file' => '', ), 'flock_ok' => '', // this file exists if we're sure that flock works in this system. )`	#
`private float`	`$_heartbeat`	`0.0`	#
`protected integer`	`$_read_attempt_limit`	`5`	#

Packages

Classes

Class waLongActionController

Direct known subclasses

Returns

Returns

Returns

Parameters

Returns

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws

Parameters

Returns

Throws