Modul:Timing

-- module timing individual functions
-- @license (CC-BY-SA-3.0)
-- @copyright John Erling Blad <jeblad@gmail.com>

-- @var The table holding this modules exported members
local p = {
	['_count'] = 100,
	['_sets'] = 10,
}

-- access function for the number of items in each sets
-- @param number new count of items in each set
-- @return number of items in each set
function p.count( num )
	if num then
		assert(num>0, "Value of 'num' can\'t be zero")
		p._count = num
	end
	return p._count
end

-- access function for the number of sets
-- @param number new count of sets
-- @return number of sets
function p.sets( num )
	if num then
		assert(num>0, "Value of 'sets' can\'t be zero")
		p._sets = num
	end
	return p._sets
end

-- calculate the statistics for time series, and report mean and variance
-- for some background on this calculation, see [[w:en:average]] and [[w:en:Standard deviation]]
-- @param table timing is a sequence of time differences
-- @return table of mean and variance
function p.stats( timing )
	local minVal = timing[1]
	local maxVal = timing[1]
	local sqr,mean=0,0
	for i,v in ipairs(timing) do
		minVal = v < minVal and v or minVal
		maxVal = v > maxVal and v or maxVal
		mean = v + mean
		sqr = math.pow(v,2) + sqr
	end
	mean = mean / #timing
	local var = (sqr / #timing) - math.pow(mean,2)
	return { mean, var, minVal, maxVal }
end

-- runner that iterates a provided function while taking the time for each chunk of iterations
-- @param function func that is the kernel of the iterations
-- @return table of runtime for the given function
function p.runner(func, ...)
	-- measure the function
	local time = {}
	for i=1,p._sets do
		time[i] = os.clock()
		for j=1,p._count do
			func(...)
		end
		time[i] = os.clock() - time[i]
	end
	
	assert(#time>0, "No entries for time measurements")
	
	return time
end

-- combine the measurements into a new form
-- for some background on this calculation, see [[w:en:Sum of normally distributed random variables]]
-- @param table tick stats for the baseline
-- @param table tack stats for the observed function
-- @return table with the combined stats, shifted from variance to standard deviation
function p.combine(tick, tack)
	-- adjust the actual measurement for the baseline
	return { tack[1] - tick[1], math.pow(tack[2] + tick[2], 0.5), tick[3], tick[4] }
end

-- formatter for the result produced by the runner
-- @param table timing as a mean and a standard deviation
-- @return string describing the result
function p.report( timing )
	local messages = {}
	messages['call-result'] = 'Each call was running for about $1 seconds.\n'
	messages['mean-result'] = '\tMean runtime for each set was $1 seconds,\n\twith standard deviation of $2 seconds,\n\tminimum $3, maximum $4.\n'
	messages['overall-result'] = '\tTotal time spent was about $1 seconds.\n'
	messages['load-result'] = 'Relative load is estimated to $1.\n'
	
	local function g( key, ...)
		local msg = mw.message.new( 'timing-' .. key )
		if msg:isBlank() then
			msg = mw.message.newRawMessage( messages[key] )
		end
		return msg
	end
	
	local function f(formatstring, nums)
		local formatted = {}
		for _,v in ipairs(nums) do
			formatted[1+#formatted] = string.format( formatstring, v )
		end
		return formatted
	end
	
	local strings = {
		g('call-result'):numParams(unpack(f('%.1e', timing[1]))):plain(),
		g('mean-result'):numParams(unpack(f('%.1e', timing[2]))):plain(),
		g('overall-result'):numParams(unpack(f('%.1e', timing[3]))):plain(),
		g('load-result'):numParams(unpack(f('%.1f', timing[4]))):plain()
	}
	return table.concat(strings, '')
end

-- a dummy function that is used for a baseline measure
-- @return nil
function p.nop()
	return nil
end

-- metatable for the export
local mt = {
	-- call-form of the table, with arguments as if it were runner()
	-- @paramfunction func that is the kernel of the iterations
	-- @return string describing the result
	__call = function (self, func, ...)
		-- resolve to the same level
		local f1 = p.nop
		local f2 = func
		
		-- start the clock
		local tick = os.clock()
	
		local baseline = self.stats( self.runner(f1, ...) )
		local actual = self.stats( self.runner(f2, ...) )
		
		local combined = self.combine(baseline, actual)
		local tack = os.clock()
		return self.report({{ combined[1] / p._count }, combined, { tack - tick }, {actual[1]/baseline[1]}})
	end
}

-- install the metatable
setmetatable(p, mt)

-- done
return p