WallClockSynchroniser

@interface WallClockSynchroniser : NSObject

A configurator component to setup all the sub-components for a WallClock time synchronisation.

To perform WallClock time synchronisation, the following components are required:

  1. A WallClock server’s host address and port number

  2. A local WallClock that will be synchronised.In this implementation, the same WallClock in used to timestamp WC protocol messages.

  3. A WC protocol client (WCProtocolClient object) to send WC requests and receive WC responses. On reception of WC response messages, the WCProtocolClient object creates a Candidate measurement object and submits it to a CandidateSink object for further proccesing.

  4. A Candidate measurement handler object of the type CandidateSink.

  5. An algorithm object to process Candidates and readjust the local WallClock’s offset. WC algorithms must conform to the IWCAlgo protocol.

  6. A list of filters (IFilter-conforming instances) to reject unsuitable Candidates e.g. a candidates with an RTT that exceeds a specified threshold.

The WCProtocolClient and CandidateSink components are loaded by the configurator. The algorithm and filter list have to be specified by the user when the configurator WallClockClientComponent is initialised.

  • WallClock server’s host address

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSString *WCServerHost;

    Swift

    var wcServerHost: String! { get }

  • WallClock server’s port number

    Declaration

    Objective-C

    @property (readonly, nonatomic) int port;

    Swift

    var port: Int32 { get }

  • A reference to a WallClock that is used for timestamping WC request and response messages. The WallClock’s offset is also adjusted by the CandidateSink’s WC algorithm object when Candidate measurements are processed.

    Declaration

    Objective-C

    @property (nonatomic, strong) TunableClock* wallClockRef

  • A WCProtocolClient object for sending WC requests and generating Candidate measurements

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic) WCProtocolClient *wcProtoClient;

    Swift

    var wcProtoClient: WCProtocolClient! { get }

  • A component to process candidate measurements collected by the WCProtocolClient component and use an algorithm to calculate offset and dispersion value of the wallclock. If the candidate being processed is better than our best candidate (e.g. lower dispersion, lower RTT, etc), then the CandidateSink object readjusts

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic) CandidateSink *candidateHandler;

    Swift

    var candidateHandler: CandidateSink! { get }

  • WC algorithm e.g. LowestDispersionAlgorithm to process candidates

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic) id<IWCAlgo> algorithm;

    Swift

    var algorithm: IWCAlgo! { get }

  • A list of filters to reject unsuitable candidates.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic) NSArray *filters;

    Swift

    var filters: [Any]! { get }

  • Undocumented

    Declaration

    Objective-C

    @interface WallClockSynchroniser : NSObject

  • Initialise the WallClockClientComponent, a configurator object for the WallClock time synchronisation framework. A default algorithm (LowestDispersionAlgorithm) and a default filter (RTTThresholdFilter) are loaded

    Declaration

    Objective-C

    - (instancetype)initWithWCServer:(NSString *)address
                            Port:(int)port
                       WallClock:(id)wallclock;

    Swift

    init!(wcServer address: String!, port: Int32, wallClock wallclock: Any!)

    Parameters

    address
    • hostname or IP address of WallClock server host
    port
    • port number of WallClock server
    wallclock
    • - a TunableClock instance serving as a local WallClock

    Return Value

    a WallClockClientComponent instance

  • Initialise the WallClockClientComponent, a configurator object for the WallClock time synchronisation framework.

    Declaration

    Objective-C

    - (instancetype)initWithWCServer:(NSString *)address
                            Port:(int)port
                       WallClock:(id)wallclock
                       Algorithm:(id<IWCAlgo>)algo
                      FilterList:(NSArray *)filters;

    Swift

    init!(wcServer address: String!, port: Int32, wallClock wallclock: Any!, algorithm algo: IWCAlgo!, filterList filters: [Any]!)

    Parameters

    address
    • hostname or IP address of WallClock server host
    port
    • port number of WallClock server
    wallclock
    • a TunableClock instance serving as a local WallClock
    algorithm
    • A IWCAlgo protocol-conforming algorithm for processing Candidates
    filters
    • List of filters. Each filter should conform to the IFilter protocol

    Return Value

    a WallClockClientComponent instance

  • Start WallClock time synchronisation

    Declaration

    Objective-C

    - (void)start;

    Swift

    func start()

  • Pause WallClock time synchronisation. To restart, call start method

    Declaration

    Objective-C

    - (void)pause;

    Swift

    func pause()

  • Stop WallClock time synchronisation

    Declaration

    Objective-C

    - (void)stop;

    Swift

    func stop()

  • Get the percentage of bad candidate measurements i.e. candidates rejected by filters

    Declaration

    Objective-C

    - (float)getCandidatesDroppedPercent;

    Swift

    func getCandidatesDroppedPercent() -> Float

    Return Value

    percentage of bad candidate measurements

  • Undocumented

    Declaration

    Objective-C

    @interface WallClockSynchroniser : NSObject

  • Get the percentage of candidate measurements that led to a wallclock time readjustment.

    Declaration

    Objective-C

    - (float)getUsefulCandidatesPercent;

    Swift

    func getUsefulCandidatesPercent() -> Float

    Return Value

    percentage of useful candidate measurements

  • Get the current dispersion of the best candidate.

    Declaration

    Objective-C

    - (int64_t)getCurrentDispersion;

    Swift

    func getCurrentDispersion() -> Int64

    Return Value

    the currently best dispersion value in nanoseconds

  • get best offset

    Declaration

    Objective-C

    - (int64_t)getCandidateOffset;

    Swift

    func getCandidateOffset() -> Int64

    Return Value

    get best candidate’s offset

  • Get the current best candidate seen by the algorithm.

    Declaration

    Objective-C

    - (Candidate *)getBestCandidate;

    Swift

    func getBestCandidate() -> Candidate!

    Return Value

    the current best candidate (a Candidate object)