High Precision Time Stamps.xml

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>HighPrecisionTimeStamps</name>
    </assembly>
    <members>
        <member name="T:HpTimesStamps.ITimeStampUtil">
            <summary>
            Note that the times retrieved are not more accurate in ABSOLUTE terms.
            If <see cref="P:HpTimesStamps.ITimeStampUtil.IsHighPrecision"/> successive calls to get timestamp will
            be more accurate (with respect to each other, within the <see cref="P:HpTimesStamps.ITimeStampUtil.CalibrationWindow"/>).  
            </summary>
        </member>
        <member name="P:HpTimesStamps.ITimeStampUtil.StopWatchTicksPerSecond">
            <summary>
            Number of ticks per second by the stop watch's (and if <see cref="P:HpTimesStamps.ITimeStampUtil.IsHighPrecision"/>, the HPET's)
            reckoning
            </summary>
        </member>
        <member name="P:HpTimesStamps.ITimeStampUtil.DateTimeTicksPerSecond">
            <summary>
            Number of ticks per second by DateTime and TimeSpan's reckoning
            </summary>
        </member>
        <member name="P:HpTimesStamps.ITimeStampUtil.IsHighPrecision">
            <summary>
            Check whether high precision timestamps are possible, if not,
            might as well use DateTime.Now (unless you want hp wherever possible)
            </summary>
        </member>
        <member name="P:HpTimesStamps.ITimeStampUtil.CurrentLocalTimeStamp">
            <summary>
            Like DateTime.Now but based off of a reading from the high precision event timer
            and then converted into terms of the local time system
            </summary>
        </member>
        <member name="P:HpTimesStamps.ITimeStampUtil.CurrentUtcTimeStamp">
            <summary>
            Like DateTime.UtcNow, but based off of a reading from the high precision event timer
            then converted into terms of utc time system
            </summary>
        </member>
        <member name="P:HpTimesStamps.ITimeStampUtil.CalibrationWindow">
            <summary>
            The amount of time calibration lasts for.
            </summary>
        </member>
        <member name="P:HpTimesStamps.ITimeStampUtil.TimeSinceLastCalibration">
            <summary>
            Amount of time since last calibration.
            </summary>
        </member>
        <member name="P:HpTimesStamps.ITimeStampUtil.IsCalibrated">
            <summary>
            Whether the util is calibrated at present
            </summary>
        </member>
        <member name="M:HpTimesStamps.ITimeStampUtil.Calibrate">
            <summary>
            Manually force a calibration.  If not calibrated, upon call to
            <see cref="P:HpTimesStamps.ITimeStampUtil.CurrentLocalTimeStamp"/> or <see cref="P:HpTimesStamps.ITimeStampUtil.CurrentUtcTimeStamp"/> calibration will
            be performed before TimeStamp retrieval causing a delay.  If you want to avoid that,
            calling this will do the trick.
            </summary>
        </member>
        <member name="T:HpTimesStamps.TimeStampSource">
            <summary>
            Calibration is PER THREAD.  Calls are therefore thread-safe, but calibration may need to be done
            on each thread using this resource.
            </summary>
            <seealso cref="T:HpTimesStamps.TimeStampUtil">for more information</seealso>
        </member>
        <member name="P:HpTimesStamps.TimeStampSource.IsHighPrecision">
            <summary>
            True if high precision timestamps are used, false otherwise.
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampSource.UtcNow">
            <summary>
            High precision (if available) Utc timestamp
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampSource.Now">
            <summary>
            High precision (if available) timestamp available here
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampSource.NeedsCalibration">
            <summary>
            True if calibration is needed on THIS thread, false otherwise
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampSource.TimeSinceCalibration">
            <summary>
            How long has it been since calibration (on THIS thread)
            </summary>
        </member>
        <member name="M:HpTimesStamps.TimeStampSource.Calibrate">
            <summary>
            Perform calibration now for THIS thread
            </summary>
        </member>
        <member name="T:HpTimesStamps.TimeStampUtil">
             <summary>
             This struct is used in <see cref="T:HpTimesStamps.TimeStampSource"/> to provide high precision timestamps on a per thread basis.
             These timestamps have exactly the same format as timestamps retrieved by <see cref="P:System.DateTime.Now"/>, which
             corresponds to <see cref="P:HpTimesStamps.TimeStampUtil.CurrentLocalTimeStamp"/> herein and to <see cref="P:HpTimesStamps.TimeStampSource.Now"/> and <see cref="P:System.DateTime.UtcNow"/>,
             which corresponds to <see cref="P:HpTimesStamps.TimeStampUtil.CurrentUtcTimeStamp"/> herein and to <see cref="P:HpTimesStamps.TimeStampSource.UtcNow"/>.
            
             Please note that this (where hardware makes it possible) provides high PRECISION timestamps, not necessarily high ACCURACY
             timestamps.  DateTime.Now or .UtcNow may actually provide timestamps that are more accurate in terms of lack
             of deviation from official times.  These timestamps, however, should be -- on a single thread at least -- more accurate with respect
             to successively retrieved timestamps within a rather short period of time because they, where possible, make use of the hardware's high precision
             event timer.
            
             Calibration occurs on a per-thread basis by retrieving establishing an offset between the ticks value of DateTime.Now and the
             high precision event timer.  It then converts subsequent readings from the high precision timer back into DateTime format.
            
             As the time since <see cref="P:HpTimesStamps.TimeStampUtil.TimeSinceLastCalibration"/> increases, the high precision timer becomes LESS ACCURATE vis-a-vis
             "absolute" real time, but remains accurate with respect to the elapsed time the last time stamp was retrieved, a short time ago.
             Every time <see cref="P:HpTimesStamps.TimeStampUtil.TimeSinceLastCalibration"/> elapses, the next time stamp retrieval will recalibrate, causing retrieval to
             take slightly longer.  You can call <see cref="M:HpTimesStamps.TimeStampUtil.Calibrate"/> manually to do this yourself immediately before retrieving timestamps.
            
             The use-case for these timestamps is when you need timestamps that are approximately accurate vis-a-vis the system clock but also
             occasionally use them to measure elapsed time between events that occur in fractions of a millisecond.  In the latter use, they should
             be far better suited than DateTime.Now.  They may be somewhat less accurate than DateTime.Now with respect to the absolute, official
             UTC time, but remain accurate enough for many such purposes.
            
             Note that this library may malfunction until recalibration if the system clock changes ... at least until recalibration occurs.
            
             This struct is a time stamp util.  It should be accessed via TimeStampSource.
             If you wish to make your own time stamp util struct, make sure it has all the same public
             methods, operators and properties that this struct has.  Then alter the alias at the top of
             <see cref="T:HpTimesStamps.TimeStampSource"/>file to use yours and then recompile.  I do not recommend using interface
             as that introduces unneeded delay.
            
             The time stamp state is all thread local.  This means that calibration is done on a per thread basis.
             
             </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampUtil.IsHighPrecision">
            <summary>
            True if a high precision event timer is available, false otherwise
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampUtil.IsCalibrated">
            <summary>
            True if the util has a current calibration.  <seealso cref="P:HpTimesStamps.TimeStampUtil.CalibrationWindow"/> for how long
            calibration lasts before becoming considered stale.
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampUtil.StopWatchTicksPerSecond">
            <summary>
            How many high precision ticks per second are there?
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampUtil.DateTimeTicksPerSecond">
            <summary>
            How many date time ticks per second are there?
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampUtil.TimeSinceLastCalibration">
            <summary>
            How much time has elapsed since last calibration (per thread)
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampUtil.CalibrationWindow">
            <summary>
            How much time may elapse before calibration becomes considered stale.
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampUtil.CurrentUtcTimeStamp">
            <summary>
            Not yet tested; probably will not work.
            todo fixit make it work
            </summary>
        </member>
        <member name="P:HpTimesStamps.TimeStampUtil.CurrentLocalTimeStamp">
            <summary>
            Analog for <seealso cref="P:System.DateTime.Now"/> uses higher precision
            </summary>
        </member>
        <member name="M:HpTimesStamps.TimeStampUtil.Calibrate">
            <summary>
            Perform calibration
            </summary>
        </member>
        <member name="M:HpTimesStamps.TimeStampUtil.op_Equality(HpTimesStamps.TimeStampUtil,HpTimesStamps.TimeStampUtil)">
            <summary>
            Always true ... all state is thread local and static
            </summary>
            <returns>true</returns>
        </member>
        <member name="M:HpTimesStamps.TimeStampUtil.op_Inequality(HpTimesStamps.TimeStampUtil,HpTimesStamps.TimeStampUtil)">
            <summary>
            Always false, all state is thread local and static
            </summary>
            <returns>false</returns>
        </member>
        <member name="M:HpTimesStamps.TimeStampUtil.Equals(HpTimesStamps.TimeStampUtil)">
            <summary>
            Always true ... all state is thread local and static
            </summary>
            <returns>true</returns>
        </member>
        <member name="M:HpTimesStamps.TimeStampUtil.GetHashCode">
            <summary>
            397 is always the hash code.  All instances are considered equal
            </summary>
            <returns>397</returns>
        </member>
        <member name="M:HpTimesStamps.TimeStampUtil.Equals(HpTimesStamps.ITimeStampUtil)">
            <summary>
            True if <paramref name="other"/> is a not null and is of type <see cref="T:HpTimesStamps.TimeStampUtil"/>,
            false otherwise.
            </summary>
            <param name="other">Another object implementing this interface</param>
            <returns>True if <paramref name="other"/> is a not null and is of type <see cref="T:HpTimesStamps.TimeStampUtil"/>,
            false otherwise.</returns>
        </member>
        <member name="M:HpTimesStamps.TimeStampUtil.Equals(System.Object)">
            <summary>
            True if <paramref name="other"/> is a not null and is of type <see cref="T:HpTimesStamps.TimeStampUtil"/>,
            false otherwise.
            </summary>
            <param name="other">Another object implementing this interface</param>
            <returns>True if <paramref name="other"/> is a not null and is of type <see cref="T:HpTimesStamps.TimeStampUtil"/>,
            false otherwise.</returns>
        </member>
    </members>
</doc>