73 lines
32 KiB
HTML
73 lines
32 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Data.Progress.Tracker</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
|
|
window.onload = function () {pageLoad();setSynopsis("mini_Data-Progress-Tracker.html");};
|
|
//]]>
|
|
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">MissingH-1.3.0.1: Large utility library</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Copyright</th><td>Copyright (C) 2006-2011 John Goerzen</td></tr><tr><th>License</th><td>BSD3</td></tr><tr><th>Maintainer</th><td>John Goerzen <jgoerzen@complete.org> </td></tr><tr><th>Stability</th><td>provisional</td></tr><tr><th>Portability</th><td>portable</td></tr><tr><th>Safe Haskell</th><td>None</td></tr><tr><th>Language</th><td>Haskell98</td></tr></table><p class="caption">Data.Progress.Tracker</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Introduction</a></li><li><a href="#g:2">Updating</a></li><li><a href="#g:3">Reading and Processing</a></li><li><a href="#g:4">Types</a></li><li><a href="#g:5">Utilities</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>Tools for tracking the status of a long operation.</p><p>Written by John Goerzen, jgoerzen@complete.org </p><p>See also <a href="Data-Progress-Meter.html">Data.Progress.Meter</a> </p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:newProgress">newProgress</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Data-String.html#t:String">String</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="Data-Progress-Tracker.html#t:Progress">Progress</a></li><li class="src short"><a href="#v:newProgress-39-">newProgress'</a> :: <a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> -> [<a href="Data-Progress-Tracker.html#t:ProgressCallback">ProgressCallback</a>] -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="Data-Progress-Tracker.html#t:Progress">Progress</a></li><li class="src short"><a href="#v:addCallback">addCallback</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="Data-Progress-Tracker.html#t:ProgressCallback">ProgressCallback</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:addParent">addParent</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:incrP">incrP</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:incrP-39-">incrP'</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:setP">setP</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:setP-39-">setP'</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:incrTotal">incrTotal</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:setTotal">setTotal</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:finishP">finishP</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:getSpeed">getSpeed</a> :: (<a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> b), <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Fractional">Fractional</a> b) => a -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> b</li><li class="src short"><a href="#v:getETR">getETR</a> :: (<a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a>), <a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Rational">Rational</a>)) => a -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></li><li class="src short"><a href="#v:getETA">getETA</a> :: (<a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a>), <a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Rational">Rational</a>)) => a -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></li><li class="src short"><span class="keyword">data</span> <a href="#t:ProgressStatus">ProgressStatus</a> = <a href="#v:ProgressStatus">ProgressStatus</a> {<ul class="subs"><li><a href="#v:completedUnits">completedUnits</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></li><li><a href="#v:totalUnits">totalUnits</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></li><li><a href="#v:startTime">startTime</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></li><li><a href="#v:trackerName">trackerName</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Data-String.html#t:String">String</a></li><li><a href="#v:timeSource">timeSource</a> :: <a href="Data-Progress-Tracker.html#t:ProgressTimeSource">ProgressTimeSource</a></li></ul>}</li><li class="src short"><span class="keyword">data</span> <a href="#t:Progress">Progress</a></li><li class="src short"><span class="keyword">type</span> <a href="#t:ProgressTimeSource">ProgressTimeSource</a> = <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></li><li class="src short"><span class="keyword">type</span> <a href="#t:ProgressCallback">ProgressCallback</a> = <a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> -> <a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><span class="keyword">class</span> <a href="#t:ProgressStatuses">ProgressStatuses</a> a b <span class="keyword">where</span><ul class="subs"><li><a href="#v:withStatus">withStatus</a> :: a -> (<a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> -> b) -> b</li></ul></li><li class="src short"><a href="#v:defaultTimeSource">defaultTimeSource</a> :: <a href="Data-Progress-Tracker.html#t:ProgressTimeSource">ProgressTimeSource</a></li></ul></div><div id="interface"><h1 id="g:1">Introduction</h1><div class="doc"><p>ProgressTracker is a module for tracking the progress on long-running
|
|
operations. It can be thought of as the back end engine behind
|
|
a status bar. ProgressTracker can do things such as track how far along
|
|
a task is, provide an estimated time of completion, estimated time remaining,
|
|
current speed, etc. It is designed to be as generic as possible; it can even
|
|
base its speed calculations on something other than the system clock.</p><p>ProgressTracker also supports a notion of a parent tracker. This is used when
|
|
a large task is composed of several individual tasks which may also be
|
|
long-running. Downloading many large files over the Internet is a common
|
|
example of this.</p><p>Any given ProgressTracker can be told about one or more parent trackers.
|
|
When the child tracker's status is updated, the parent tracker's status is
|
|
also updated in the same manner. Therefore, the progress on each individual
|
|
component, as well as the overall progress, can all be kept in sync
|
|
automatically.</p><p>Finally, you can register callbacks. Callbacks are functions that are called
|
|
whenever the status of a tracker changes. They'll be passed the old and new
|
|
status and are intended to do things like update on-screen status displays.</p><p>The cousin module <code><a href="Data-Progress.html#t:Meter">Meter</a></code> can be used to nicely render
|
|
these trackers on a console.</p></div><div class="top"><p class="src"><a name="v:newProgress" class="def">newProgress</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Data-String.html#t:String">String</a></td><td class="doc"><p>Name of this tracker</p></td></tr><tr><td class="src">-> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></td><td class="doc"><p>Total units expected</p></td></tr><tr><td class="src">-> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="Data-Progress-Tracker.html#t:Progress">Progress</a></td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Create a new <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object with the given name and number
|
|
of total units initialized as given. The start time will be initialized
|
|
with the current time at the present moment according to the system clock.
|
|
The units completed will be set to 0, the time source will be set to the
|
|
system clock, and the parents and callbacks will be empty.</p><p>If you need more control, see 'newProgress\''.</p><p>Example:</p><pre>prog <- newProgress "mytracker" 1024</pre></div></div><div class="top"><p class="src"><a name="v:newProgress-39-" class="def">newProgress'</a> :: <a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> -> [<a href="Data-Progress-Tracker.html#t:ProgressCallback">ProgressCallback</a>] -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="Data-Progress-Tracker.html#t:Progress">Progress</a></p><div class="doc"><p>Create a new <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object initialized with the given status and
|
|
callbacks.
|
|
No adjustment to the <code><a href="Data-Progress-Tracker.html#v:startTime">startTime</a></code> will be made. If you
|
|
want to use the system clock, you can initialize <code><a href="Data-Progress-Tracker.html#v:startTime">startTime</a></code> with
|
|
the return value of <code><a href="Data-Progress-Tracker.html#v:defaultTimeSource">defaultTimeSource</a></code> and also pass <code><a href="Data-Progress-Tracker.html#v:defaultTimeSource">defaultTimeSource</a></code>
|
|
as the timing source. </p></div></div><div class="top"><p class="src"><a name="v:addCallback" class="def">addCallback</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="Data-Progress-Tracker.html#t:ProgressCallback">ProgressCallback</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>Adds an new callback to an existing <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code>. The callback will be
|
|
called whenever the object's status is updated, except by the call to finishP.</p><p>Please note that the Progress object will be locked while the callback is
|
|
running, so the callback will not be able to make any modifications to it.</p></div></div><div class="top"><p class="src"><a name="v:addParent" class="def">addParent</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a></td><td class="doc"><p>The child object</p></td></tr><tr><td class="src">-> <a href="Data-Progress-Tracker.html#t:Progress">Progress</a></td><td class="doc"><p>The parent to add to this child</p></td></tr><tr><td class="src">-> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Adds a new parent to an existing <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code>. The parent
|
|
will automatically have its completed and total counters incremented
|
|
by the value of those counters in the existing <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code>. </p></div></div><h1 id="g:2">Updating</h1><div class="top"><p class="src"><a name="v:incrP" class="def">incrP</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>Increment the completed unit count in the <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object
|
|
by the amount given. If the value as given exceeds the total, then
|
|
the total will also be raised to match this value so that the
|
|
completed count never exceeds the total.</p><p>You can decrease the completed unit count by supplying a negative number
|
|
here. </p></div></div><div class="top"><p class="src"><a name="v:incrP-39-" class="def">incrP'</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>Like <code><a href="Data-Progress-Tracker.html#v:incrP">incrP</a></code>, but never modify the total. </p></div></div><div class="top"><p class="src"><a name="v:setP" class="def">setP</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>Set the completed unit count in the <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object to the specified
|
|
value. Unlike <code><a href="Data-Progress-Tracker.html#v:incrP">incrP</a></code>, this function sets the count to a specific value,
|
|
rather than adding to the existing value. If this value exceeds the total,
|
|
then the total will also be raised to match this value so that the completed
|
|
count never exceeds teh total. </p></div></div><div class="top"><p class="src"><a name="v:setP-39-" class="def">setP'</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>Like <code><a href="Data-Progress-Tracker.html#v:setP">setP</a></code>, but never modify the total. </p></div></div><div class="top"><p class="src"><a name="v:incrTotal" class="def">incrTotal</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>Increment the total unit count in the <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object by the amount
|
|
given. This would rarely be needed, but could be needed in some special cases
|
|
when the total number of units is not known in advance. </p></div></div><div class="top"><p class="src"><a name="v:setTotal" class="def">setTotal</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>Set the total unit count in the <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object to the specified
|
|
value. Like <code><a href="Data-Progress-Tracker.html#v:incrTotal">incrTotal</a></code>, this would rarely be needed. </p></div></div><div class="top"><p class="src"><a name="v:finishP" class="def">finishP</a> :: <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>Call this when you are finished with the object. It is especially
|
|
important to do this when parent objects are involved.</p><p>This will simply set the totalUnits to the current completedUnits count,
|
|
but will not call the callbacks. It will additionally propogate
|
|
any adjustment in totalUnits to the parents, whose callbacks <em>will</em> be
|
|
called.</p><p>This ensures that the total expected counts on the parent are always correct.
|
|
Without doing this, if, say, a transfer ended earlier than expected, ETA
|
|
values on the parent would be off since it would be expecting more data than
|
|
actually arrived. </p></div></div><h1 id="g:3">Reading and Processing</h1><div class="top"><p class="src"><a name="v:getSpeed" class="def">getSpeed</a> :: (<a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> b), <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Fractional">Fractional</a> b) => a -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> b</p><div class="doc"><p>Returns the speed in units processed per time unit. (If you are
|
|
using the default time source, this would be units processed per second).
|
|
This obtains the current speed solely from analyzing the <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object.</p><p>If no time has elapsed yet, returns 0.</p><p>You can use this against either a <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object or a <code><a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a></code>
|
|
object. This is in the IO monad because the speed is based on the current
|
|
time.</p><p>Example:</p><pre>getSpeed progressobj >>= print</pre><p>Don't let the type of this function confuse you. It is a fancy way of saying
|
|
that it can take either a <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> or a <code><a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a></code> object, and returns
|
|
a number that is valid as any Fractional type, such as a Double, Float, or
|
|
Rational. </p></div></div><div class="top"><p class="src"><a name="v:getETR" class="def">getETR</a> :: (<a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a>), <a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Rational">Rational</a>)) => a -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></p><div class="doc"><p>Returns the estimated time remaining, in standard time units. </p><p>Returns 0 whenever <code><a href="Data-Progress-Tracker.html#v:getSpeed">getSpeed</a></code> would return 0.</p><p>See the comments under <code><a href="Data-Progress-Tracker.html#v:getSpeed">getSpeed</a></code> for information about this function's type
|
|
and result. </p></div></div><div class="top"><p class="src"><a name="v:getETA" class="def">getETA</a> :: (<a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a>), <a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> a (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Rational">Rational</a>)) => a -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></p><div class="doc"><p>Returns the estimated system clock time of completion, in standard
|
|
time units. Returns the current time whenever <code><a href="Data-Progress-Tracker.html#v:getETR">getETR</a></code> would return 0.</p><p>See the comments under <code><a href="Data-Progress-Tracker.html#v:getSpeed">getSpeed</a></code> for information about this function's type
|
|
and result. </p></div></div><h1 id="g:4">Types</h1><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:ProgressStatus" class="def">ProgressStatus</a></p><div class="doc"><p>The main progress status record. </p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a name="v:ProgressStatus" class="def">ProgressStatus</a></td><td class="doc empty"> </td></tr><tr><td colspan="2"><div class="subs fields"><p class="caption">Fields</p><dl><dt class="src"><a name="v:completedUnits" class="def">completedUnits</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></dt><dd class="doc empty"> </dd><dt class="src"><a name="v:totalUnits" class="def">totalUnits</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></dt><dd class="doc empty"> </dd><dt class="src"><a name="v:startTime" class="def">startTime</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></dt><dd class="doc empty"> </dd><dt class="src"><a name="v:trackerName" class="def">trackerName</a> :: <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Data-String.html#t:String">String</a></dt><dd class="doc"><p>An identifying string</p></dd><dt class="src"><a name="v:timeSource" class="def">timeSource</a> :: <a href="Data-Progress-Tracker.html#t:ProgressTimeSource">ProgressTimeSource</a></dt><dd class="doc empty"> </dd></dl><div class="clear"></div></div></td></tr></table></div><div class="subs instances"><p id="control.i:ProgressStatus" class="caption collapser" onclick="toggleSection('i:ProgressStatus')">Instances</p><div id="section.i:ProgressStatus" class="show"><table><tr><td class="src"><a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> <a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> b</td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:Progress" class="def">Progress</a></p><div class="doc"><p>The main Progress object. </p></div><div class="subs instances"><p id="control.i:Progress" class="caption collapser" onclick="toggleSection('i:Progress')">Instances</p><div id="section.i:Progress" class="show"><table><tr><td class="src"><a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> b)</td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><span class="keyword">type</span> <a name="t:ProgressTimeSource" class="def">ProgressTimeSource</a> = <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/Prelude.html#t:Integer">Integer</a></p><div class="doc"><p>A function that, when called, yields the current time.
|
|
The default is <code><a href="Data-Progress-Tracker.html#v:defaultTimeSource">defaultTimeSource</a></code>. </p></div></div><div class="top"><p class="src"><span class="keyword">type</span> <a name="t:ProgressCallback" class="def">ProgressCallback</a> = <a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> -> <a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> -> <a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> ()</p><div class="doc"><p>The type for a callback function for the progress tracker.
|
|
When given at creation time to 'newProgress\'' or when added via <code><a href="Data-Progress-Tracker.html#v:addCallback">addCallback</a></code>,
|
|
these functions get called every time the status of the tracker changes.</p><p>This function is passed two <code><a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a></code> records: the first
|
|
reflects the status prior to the update, and the second reflects
|
|
the status after the update.</p><p>Please note that the owning <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object will be locked while the
|
|
callback is running, so the callback will not be able to make changes to it. </p></div></div><div class="top"><p class="src"><span class="keyword">class</span> <a name="t:ProgressStatuses" class="def">ProgressStatuses</a> a b <span class="keyword">where</span></p><div class="subs methods"><p class="caption">Methods</p><p class="src"><a name="v:withStatus" class="def">withStatus</a> :: a -> (<a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> -> b) -> b</p><div class="doc"><p>Lets you examine the <code><a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a></code> that is contained
|
|
within a <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object. You can simply pass
|
|
a <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object and a function to <code><a href="Data-Progress-Tracker.html#v:withStatus">withStatus</a></code>, and
|
|
<code><a href="Data-Progress-Tracker.html#v:withStatus">withStatus</a></code> will lock the <code><a href="Data-Progress-Tracker.html#t:Progress">Progress</a></code> object (blocking any
|
|
modifications while you are reading it), then pass the object
|
|
to your function. If you happen to already have a <code><a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a></code>
|
|
object, withStatus will also accept it and simply pass it unmodified
|
|
to the function. </p></div></div><div class="subs instances"><p id="control.i:ProgressStatuses" class="caption collapser" onclick="toggleSection('i:ProgressStatuses')">Instances</p><div id="section.i:ProgressStatuses" class="show"><table><tr><td class="src"><a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> <a href="Data-Progress-Tracker.html#t:ProgressStatus">ProgressStatus</a> b</td><td class="doc empty"> </td></tr><tr><td class="src"><a href="Data-Progress-Tracker.html#t:ProgressStatuses">ProgressStatuses</a> <a href="Data-Progress-Tracker.html#t:Progress">Progress</a> (<a href="file:///usr/local/Cellar/ghc/7.10.1/share/doc/ghc/html/libraries/base-4.8.0.0/System-IO.html#t:IO">IO</a> b)</td><td class="doc empty"> </td></tr></table></div></div></div><h1 id="g:5">Utilities</h1><div class="top"><p class="src"><a name="v:defaultTimeSource" class="def">defaultTimeSource</a> :: <a href="Data-Progress-Tracker.html#t:ProgressTimeSource">ProgressTimeSource</a></p><div class="doc"><p>The default time source for the system. This is defined as:</p><pre>getClockTime >>= (return . clockTimeToEpoch)</pre></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.16.0</p></div></body></html> |