core\progress\db_updater Class Reference

Progress handler that updates a database table with the progress. More...

Inheritance diagram for core\progress\db_updater:

Public Member Functions
	__construct ($recordid, $table, $field, $interval=5)
	Constructs the progress reporter.
	end_progress ()
	Marks the end of an operation that will display progress.
	get_current_description ()
	get_current_max ()
	Checks max value of current progress section.
	get_progress_count ()
	Obtains current indeterminate progress in a way suitable for adding to the progress display.
	get_progress_proportion_range ()
	Obtains current progress in a way suitable for drawing a progress bar.
int	increment_progress ($incby=1)
	An alternative to calling progress.
	is_in_progress_section ()
	progress ($progress=self::INDETERMINATE)
	Indicates that progress has occurred.
	start_progress ($description, $max=self::INDETERMINATE, $parentcount=1)
	Marks the start of an operation that will display progress.
	update_progress ()
	Updates the progress in the database.

Public Attributes
int const	INDETERMINATE = -1
	Constant indicating that the number of progress calls is unknown.
int const	TIME_LIMIT_WITHOUT_PROGRESS = 3600
	This value is set rather high to ensure there are no regressions from previous behaviour.

Protected Member Functions
	get_time ()
	Gets time (this is provided so that unit tests can override it).

Protected Attributes
int	$count
	Number of progress calls (restricted to ~ 1/second).
array	$currents = array()
	Array of current progress values.
array	$descriptions = array()
	Array of progress descriptions for each stack level.
string	$field = ''
	The table field to update with the progress.
integer	$interval = 5
	The maximum frequency in seconds to update the database (default 5 seconds).
int	$lastprogresstime
	Time of last progress call.
array	$maxes = array()
	Array of maximum progress values for each stack level.
integer	$nextupdate = 0
	The timestamp of when the next progress update to the database will be.
int[]	$parentcounts = array()
	Array of counts within parent progress entry (ignored for first)
integer	$recordid = 0
	The primary key of the database record to update.
string	$table = ''
	The database table to insert the progress updates into.

Detailed Description

Progress handler that updates a database table with the progress.

Copyright

2018 Matt Porritt mattp.nosp@m.@cat.nosp@m.alyst.nosp@m.-au..nosp@m.net

License

http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Constructor & Destructor Documentation

__construct()

core\progress\db_updater::__construct	(		$recordid,
			$table,
			$field,
			$interval = 5 )

Constructs the progress reporter.

Parameters

int	$recordid	The primary key of the database record to update.
string	$table	The databse table to insert the progress updates into.
string	$field	The table field to update with the progress.
int	$interval	The maximum frequency in seconds to update the database (default 5 seconds).

Member Function Documentation

end_progress()

core\progress\base::end_progress ( )

inherited

Marks the end of an operation that will display progress.

This must be paired with each start_progress call.

If there is a parent progress section, its progress will be increased automatically to reflect the end of the child section.

Exceptions

coding_exception

If progress hasn't been started

get_current_description()

core\progress\base::get_current_description ( )

inherited

Exceptions

coding_exception

Return values

string

Current progress section description

get_current_max()

core\progress\base::get_current_max ( )

inherited

Checks max value of current progress section.

Return values

int	Current max value - may be core::progress::base::INDETERMINATE.

Exceptions

coding_exception

If not in a progress section

get_progress_count()

core\progress\base::get_progress_count ( )

inherited

Obtains current indeterminate progress in a way suitable for adding to the progress display.

This returns the number of indeterminate calls (at any level) during the lifetime of this progress reporter, whether or not there is a current indeterminate step. (The number will not be ridiculously high because progress calls are limited to one per second.)

Return values

int	Number of indeterminate progress calls

get_progress_proportion_range()

core\progress\base::get_progress_proportion_range ( )

inherited

Obtains current progress in a way suitable for drawing a progress bar.

Progress is returned as a minimum and maximum value. If there is no indeterminate progress, these values will be identical. If there is intermediate progress, these values can be different. (For example, if the top level progress sections is indeterminate, then the values will always be 0.0 and 1.0.)

Return values

array

Minimum and maximum possible progress proportions

get_time()

core\progress\base::get_time ( )

protectedinherited

Gets time (this is provided so that unit tests can override it).

Return values

int	Current system time

increment_progress()

int core\progress\base::increment_progress ( $incby = 1 )

inherited

An alternative to calling progress.

This keeps track of the number of items done internally. Call this method with no parameters to increment the internal counter by one or you can use the $incby parameter to specify a positive change in progress. The internal progress counter should not exceed $max as passed to start_progress for this section.

If you called start_progress with parameter INDETERMINATE then you cannot call this method.

$incby The positive change to apply to the internal progress counter. Defaults to 1.

is_in_progress_section()

core\progress\base::is_in_progress_section ( )

inherited

Return values

bool	True if currently inside a progress section

progress()

core\progress\base::progress ( $progress = self::INDETERMINATE )

inherited

Indicates that progress has occurred.

The progress value should indicate the total progress so far, from 0 to the value supplied for $max (inclusive) in start_progress.

You do not need to call this function for every value. It is OK to skip values. It is also OK to call this function as often as desired; it doesn't update the display if called more than once per second.

It must be INDETERMINATE if start_progress was called with $max set to INDETERMINATE. Otherwise it must not be indeterminate.

Parameters

int

$progress

Progress so far

Exceptions

coding_exception

If progress value is invalid

start_progress()

core\progress\base::start_progress ( $description, $max = self::INDETERMINATE, $parentcount = 1 )

inherited

Marks the start of an operation that will display progress.

This can be called multiple times for nested progress sections. It must be paired with calls to end_progress.

The progress maximum may be self::INDETERMINATE if the current operation has an unknown number of steps. (This is default.)

Calling this function will always result in a new display, so this should not be called exceedingly frequently.

When it is complete by calling end_progress(), each start_progress section automatically adds progress to its parent, as defined by $parentcount.

Parameters

string	$description	Description to display
int	$max	Maximum value of progress for this section
int	$parentcount	How many progress points this section counts for

Exceptions

coding_exception

If max is invalid

update_progress()

core\progress\db_updater::update_progress

(

)

Updates the progress in the database.

Database update frequency is set by $interval.

See also

core\progress\base\update_progress()

Reimplemented from core\progress\base.

Member Data Documentation

$interval

integer core\progress\db_updater::$interval = 5

protected

The maximum frequency in seconds to update the database (default 5 seconds).

Lower values will increase database calls.

TIME_LIMIT_WITHOUT_PROGRESS

int const core\progress\base::TIME_LIMIT_WITHOUT_PROGRESS = 3600

inherited

This value is set rather high to ensure there are no regressions from previous behaviour.

For testing, it may be useful to set the frontendservertimeout config option to a lower value, such as 180 seconds (default for some commercial products).

The number of seconds that can pass without progress() calls.

---

The documentation for this class was generated from the following file:

• lib/classes/progress/db_updater.php