Child Reporters

SLaks edited this page Jun 30, 2011 · 6 revisions
Clone this wiki locally

Child progress reporters are special IProgressReporter implementations that update the progress of a parent reporter. They are used by operations which contain multiple child operations that can themselves report progress.

For example, given a function that downloads a file and reports progress, one can write another function that downloads ten files and reports the overall progress of the entire operation. This function would download each individual file with a child reporter that accounts for one tenth of the entire progress.

##Types Child reporters come in two types:

  • Scaled child reporters scale the progress reported by the child operation to account for a fixed portion of the total progress for the parent operation. Scaled progress reporters are used when the composition of the child operations is not known in advance. The Maximum of a scaled progress reporter is used to scale its value to the portion of the parent reporter that it occupies. Going back to the previous example, the parent operation would set its maximum progress to 1,000, and it would pass scaled child reporters to the download method that go up to 100. Thus, the progress of each file would contribute 100 units to the parent operation, regardless of the maximum or units of the child operation.
    If some files are bigger than others, the overall progress flow will be uneven, since all of the files will contribute equally towards the overall progress. If the durations of the child operations can be approximated, this effect can be mitigated by specifying larger maximums for the longer child operations.

  • Unscaled child reporters contribute their progress directly to the progress of the parent reporter, without scaling it at all. Unscaled child reporters are used when the parent operation knows the maximums that will be used by the child operations a priori, and has adjusted its own maximum to include the sums of the maximums of the child operations. An unscaled progress reporter ignores its Maximum property; its value is always added directly to the base value of the parent from when the child was created. The previous example of downloading multiple files cannot use unscaled child reporters, since the parent operation doesn't know the file sizes in advance.
    The opposite case of uploading files can use unscaled child operations. The upload method would take a progress reporter and set its maximum to the size of the file. The parent operation would set its maximum to the sum of the sizes of the files, then pass unscaled child operations to the upload method.

All child reporters obey the rules for IProgressReporters and are indistinguishable from other reporters.

Child reporters are created by extension methods on the IProgressReporter interface.

#Properties

A child reporter's caption is passed directly to the parent reporter.

If a child reporter becomes indeterminate (by setting Maximum to -1), the parent reporter is not affect. (the overall parent operation still has a definite progress, so there is no reason to become indeterminate)

Child reporters do not affect theirs parent reporters' cancelability. If the parent operation or reporter cannot be canceled, the child reporter will never be cancellable (even if the child operation can be cancellable, the parent won't know what to do with it).
If the parent operation is cancellable, the reporter will always be cancellable. If the child operation sets AllowCancellation to false, the parent reporter will still be cancellable, but the child reporter's AllowCancellation and WasCanceled properties will return false (to conform to the IProgressreporter spec). If the user then cancels, the child operation will run to completion, and the parent operation will then detect the cancellation.