From 439ca291bccbd084a86bd5e59bfdd7e3a8b7921e Mon Sep 17 00:00:00 2001 From: Krunoslav Zaher Date: Wed, 30 Dec 2015 15:13:57 +0100 Subject: [PATCH] Updates `Scheduler` documentation. --- CHANGELOG.md | 4 +- Rx.xcworkspace/contents.xcworkspacedata | 2 +- .../RxExample-iOS-no-module.xcscheme | 2 +- .../xcschemes/RxExample-iOS.xcscheme | 4 +- RxSwift/SchedulerType.swift | 4 +- RxSwift/Schedulers/HistoricalScheduler.swift | 9 +++- .../HistoricalSchedulerTimeConverter.swift | 42 +++++++++++++++- .../Schedulers/VirtualTimeConverterType.swift | 47 +++++++++++++++++- RxSwift/Schedulers/VirtualTimeScheduler.swift | 4 +- .../TestSchedulerVirtualTimeConverter.swift | 49 ++++++++++++++++++- .../TestVirtualScheduler.swift | 4 +- 11 files changed, 154 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 89a51615..54ca7e92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,9 @@ All notable changes to this project will be documented in this file. * use cases like `cell.rx_sentMessage("prepareForReuse")` are now supported. * Linux support (proof of concept, but single threaded mode works) * more info in [Documentation/Linux.md](https://github.com/ReactiveX/RxSwift/blob/master/Documentation/Linux.md) -* Initial support for `Swift Package Manager` (works on `Linux`, still can't compile `RxCocoa` on `OSX`) +* Initial support for `Swift Package Manager` + * works on `Linux` (`RxSwift`, `RxBlocking`, `RxTests`) + * doesn't work on OSX because it can't compile `RxCocoa` and `RxTests` (because of inclusion of `XCTest` extensions), but OSX has two other package managers and manual method. * Project content is linked to `Sources` automagically using custom tool * Adds `VirtualTimeScheduler` to `RxSwift` * Adds `HistoricalScheduler` to `RxSwift` diff --git a/Rx.xcworkspace/contents.xcworkspacedata b/Rx.xcworkspace/contents.xcworkspacedata index 9755774b..2f199f58 100644 --- a/Rx.xcworkspace/contents.xcworkspacedata +++ b/Rx.xcworkspace/contents.xcworkspacedata @@ -64,7 +64,7 @@ location = "group:common.sh"> + location = "group:/Users/kzaher/Projects/RxSwift/scripts/package-spm.swift"> diff --git a/RxExample/RxExample.xcodeproj/xcshareddata/xcschemes/RxExample-iOS-no-module.xcscheme b/RxExample/RxExample.xcodeproj/xcshareddata/xcschemes/RxExample-iOS-no-module.xcscheme index b81f5903..a3b59031 100644 --- a/RxExample/RxExample.xcodeproj/xcshareddata/xcschemes/RxExample-iOS-no-module.xcscheme +++ b/RxExample/RxExample.xcodeproj/xcshareddata/xcschemes/RxExample-iOS-no-module.xcscheme @@ -42,7 +42,7 @@ @@ -52,7 +52,7 @@ { + /** + Creates a new historical scheduler with initial clock value. + + - parameter initialClock: Initial value for virtual clock. + */ public init(initialClock: RxTime = NSDate(timeIntervalSince1970: 0)) { - //print(initialClock) super.init(initialClock: initialClock, converter: HistoricalSchedulerTimeConverter()) } diff --git a/RxSwift/Schedulers/HistoricalSchedulerTimeConverter.swift b/RxSwift/Schedulers/HistoricalSchedulerTimeConverter.swift index b93ed3b4..b16b8a2b 100644 --- a/RxSwift/Schedulers/HistoricalSchedulerTimeConverter.swift +++ b/RxSwift/Schedulers/HistoricalSchedulerTimeConverter.swift @@ -8,30 +8,68 @@ import Foundation +/** + Converts historial virtual time into real time. + + Since historical virtual time is also measured in `NSDate`, this converter is identity function. + */ public struct HistoricalSchedulerTimeConverter : VirtualTimeConverterType { + /** + Virtual time unit used that represents ticks of virtual clock. + */ public typealias VirtualTimeUnit = RxTime + + /** + Virtual time unit used to represent differences of virtual times. + */ public typealias VirtualTimeIntervalUnit = RxTimeInterval + /** + Returns identical value of argument passed because historical virtual time is equal to real time, just + decoupled from local machine clock. + */ public func convertFromVirtualTime(virtualTime: VirtualTimeUnit) -> RxTime { return virtualTime } + /** + Returns identical value of argument passed because historical virtual time is equal to real time, just + decoupled from local machine clock. + */ public func convertToVirtualTime(time: RxTime) -> VirtualTimeUnit { return time } + /** + Returns identical value of argument passed because historical virtual time is equal to real time, just + decoupled from local machine clock. + */ public func convertFromVirtualTimeInterval(virtualTimeInterval: VirtualTimeIntervalUnit) -> RxTimeInterval { return virtualTimeInterval } + /** + Returns identical value of argument passed because historical virtual time is equal to real time, just + decoupled from local machine clock. + */ public func convertToVirtualTimeInterval(timeInterval: RxTimeInterval) -> VirtualTimeIntervalUnit { return timeInterval } - public func addVirtualTimeAndTimeInterval(time time: VirtualTimeUnit, timeInterval: VirtualTimeIntervalUnit) -> VirtualTimeUnit { - return time.dateByAddingTimeInterval(timeInterval) + /** + Offsets `NSDate` by time interval. + + - parameter time: Time. + - parameter timeInterval: Time interval offset. + - returns: Time offsetted by time interval. + */ + public func offsetVirtualTime(time time: VirtualTimeUnit, offset: VirtualTimeIntervalUnit) -> VirtualTimeUnit { + return time.dateByAddingTimeInterval(offset) } + /** + Compares two `NSDate`s. + */ public func compareVirtualTime(lhs: VirtualTimeUnit, _ rhs: VirtualTimeUnit) -> VirtualTimeComparison { switch lhs.compare(rhs) { case .OrderedAscending: diff --git a/RxSwift/Schedulers/VirtualTimeConverterType.swift b/RxSwift/Schedulers/VirtualTimeConverterType.swift index 18ceab00..1af28975 100644 --- a/RxSwift/Schedulers/VirtualTimeConverterType.swift +++ b/RxSwift/Schedulers/VirtualTimeConverterType.swift @@ -8,17 +8,60 @@ import Foundation +/** +Parametrization for virtual time used by `VirtualTimeScheduler`s. +*/ public protocol VirtualTimeConverterType { + /** + Virtual time unit used that represents ticks of virtual clock. + */ typealias VirtualTimeUnit + + /** + Virtual time unit used to represent differences of virtual times. + */ typealias VirtualTimeIntervalUnit + /** + Converts virtual time to real time. + + - parameter virtualTime: Virtual time to convert to `NSDate`. + - returns: `NSDate` corresponding to virtual time. + */ func convertFromVirtualTime(virtualTime: VirtualTimeUnit) -> RxTime + + /** + Converts real time to virtual time. + + - parameter time: `NSDate` to convert to virtual time. + - returns: Virtual time corresponding to `NSDate`. + */ func convertToVirtualTime(time: RxTime) -> VirtualTimeUnit + /** + Converts from virtual time interval to `NSTimeInterval`. + + - parameter virtualTimeInterval: Virtual time interval to convert to `NSTimeInterval`. + - returns: `NSTimeInterval` corresponding to virtual time interval. + */ func convertFromVirtualTimeInterval(virtualTimeInterval: VirtualTimeIntervalUnit) -> RxTimeInterval + + /** + Converts from virtual time interval to `NSTimeInterval`. + + - parameter timeInterval: `NSTimeInterval` to convert to virtual time interval. + - returns: Virtual time interval corresponding to time interval. + */ func convertToVirtualTimeInterval(timeInterval: RxTimeInterval) -> VirtualTimeIntervalUnit - func addVirtualTimeAndTimeInterval(time time: VirtualTimeUnit, timeInterval: VirtualTimeIntervalUnit) -> VirtualTimeUnit + /** + Offsets virtual time by virtual time interval. + + - parameter time: Virtual time. + - parameter offset: Virtual time interval. + - returns: Time corresponding to time offsetted by virtual time interval. + */ + func offsetVirtualTime(time time: VirtualTimeUnit, offset: VirtualTimeIntervalUnit) -> VirtualTimeUnit /** This is aditional abstraction because `NSDate` is unfortunately not comparable. @@ -46,7 +89,9 @@ public enum VirtualTimeComparison { lhs > rhs. */ case GreaterThan +} +extension VirtualTimeComparison { /** lhs < rhs. */ diff --git a/RxSwift/Schedulers/VirtualTimeScheduler.swift b/RxSwift/Schedulers/VirtualTimeScheduler.swift index 06fc92fd..03b542ae 100644 --- a/RxSwift/Schedulers/VirtualTimeScheduler.swift +++ b/RxSwift/Schedulers/VirtualTimeScheduler.swift @@ -102,7 +102,7 @@ public class VirtualTimeScheduler - returns: The disposable object used to cancel the scheduled action (best effort). */ public func scheduleRelativeVirtual(state: StateType, dueTime: VirtualTimeInterval, action: StateType -> Disposable) -> Disposable { - let time = _converter.addVirtualTimeAndTimeInterval(time: self.clock, timeInterval: dueTime) + let time = _converter.offsetVirtualTime(time: self.clock, offset: dueTime) return scheduleAbsoluteVirtual(state, time: time, action: action) } @@ -220,7 +220,7 @@ public class VirtualTimeScheduler public func sleep(virtualInterval: VirtualTimeInterval) { MainScheduler.ensureExecutingOnScheduler() - let sleepTo = _converter.addVirtualTimeAndTimeInterval(time: clock, timeInterval: virtualInterval) + let sleepTo = _converter.offsetVirtualTime(time: clock, offset: virtualInterval) if _converter.compareVirtualTime(sleepTo, clock).lessThen { fatalError("Can't sleep to past.") } diff --git a/RxTests/Schedulers/TestSchedulerVirtualTimeConverter.swift b/RxTests/Schedulers/TestSchedulerVirtualTimeConverter.swift index edb23431..f4620e19 100644 --- a/RxTests/Schedulers/TestSchedulerVirtualTimeConverter.swift +++ b/RxTests/Schedulers/TestSchedulerVirtualTimeConverter.swift @@ -9,8 +9,18 @@ import Foundation import RxSwift +/** + Converter from virtual time and time interval measured in `Int`s to `NSDate` and `NSTimeInterval`. +*/ public struct TestSchedulerVirtualTimeConverter : VirtualTimeConverterType { + /** + Virtual time unit used that represents ticks of virtual clock. + */ public typealias VirtualTimeUnit = Int + + /** + Virtual time unit used to represent differences of virtual times. + */ public typealias VirtualTimeIntervalUnit = Int private let _resolution: Double @@ -19,26 +29,61 @@ public struct TestSchedulerVirtualTimeConverter : VirtualTimeConverterType { _resolution = resolution } + + /** + Converts virtual time to real time. + + - parameter virtualTime: Virtual time to convert to `NSDate`. + - returns: `NSDate` corresponding to virtual time. + */ public func convertFromVirtualTime(virtualTime: VirtualTimeUnit) -> RxTime { return NSDate(timeIntervalSince1970: RxTimeInterval(virtualTime) * _resolution) } + /** + Converts real time to virtual time. + + - parameter time: `NSDate` to convert to virtual time. + - returns: Virtual time corresponding to `NSDate`. + */ public func convertToVirtualTime(time: RxTime) -> VirtualTimeUnit { return VirtualTimeIntervalUnit(time.timeIntervalSince1970 / _resolution + 0.5) } + /** + Converts from virtual time interval to `NSTimeInterval`. + + - parameter virtualTimeInterval: Virtual time interval to convert to `NSTimeInterval`. + - returns: `NSTimeInterval` corresponding to virtual time interval. + */ public func convertFromVirtualTimeInterval(virtualTimeInterval: VirtualTimeIntervalUnit) -> RxTimeInterval { return RxTimeInterval(virtualTimeInterval) * _resolution } + /** + Converts from virtual time interval to `NSTimeInterval`. + + - parameter timeInterval: `NSTimeInterval` to convert to virtual time interval. + - returns: Virtual time interval corresponding to time interval. + */ public func convertToVirtualTimeInterval(timeInterval: RxTimeInterval) -> VirtualTimeIntervalUnit { return VirtualTimeIntervalUnit(timeInterval / _resolution + 0.5) } - public func addVirtualTimeAndTimeInterval(time time: VirtualTimeUnit, timeInterval: VirtualTimeIntervalUnit) -> VirtualTimeUnit { - return time + timeInterval + /** + Adds virtual time and virtual time interval. + + - parameter time: Virtual time. + - parameter offset: Virtual time interval. + - returns: Time corresponding to time offsetted by virtual time interval. + */ + public func offsetVirtualTime(time time: VirtualTimeUnit, offset: VirtualTimeIntervalUnit) -> VirtualTimeUnit { + return time + offset } + /** + Compares virtual times. + */ public func compareVirtualTime(lhs: VirtualTimeUnit, _ rhs: VirtualTimeUnit) -> VirtualTimeComparison { if lhs < rhs { return .LessThan diff --git a/Tests/RxSwiftTests/TestImplementations/TestVirtualScheduler.swift b/Tests/RxSwiftTests/TestImplementations/TestVirtualScheduler.swift index dd61e0aa..733f904a 100644 --- a/Tests/RxSwiftTests/TestImplementations/TestVirtualScheduler.swift +++ b/Tests/RxSwiftTests/TestImplementations/TestVirtualScheduler.swift @@ -41,8 +41,8 @@ struct TestVirtualSchedulerVirtualTimeConverter : VirtualTimeConverterType { return Int(timeInterval / 10.0) } - func addVirtualTimeAndTimeInterval(time time: VirtualTimeUnit, timeInterval: VirtualTimeIntervalUnit) -> VirtualTimeUnit { - return time + timeInterval + func offsetVirtualTime(time time: VirtualTimeUnit, offset: VirtualTimeIntervalUnit) -> VirtualTimeUnit { + return time + offset } func compareVirtualTime(lhs: VirtualTimeUnit, _ rhs: VirtualTimeUnit) -> VirtualTimeComparison {