/// <summary> /// Used by the slave to requests a new time interval from the source. /// This method blocks current thread until the time interval is granted. /// </summary> /// <remarks> /// This method will return immediately when the handle is disabled or detached. /// It is illegal to call this method twice in a row if the first call was successful (returned true). It must always be followed by calling <see cref="ReportBackAndContinue"> or <see cref="ReportBackAndBreak">. /// </remarks> /// <returns> /// True if the interval was granted or False when this call was interrupted as a result of detaching or disabling. /// If it returned true, <paramref name="interval"> contains the amount of virtual time to be used by the sink. It is the sum of time interval granted by the source (using <see cref="GrantInterval">) and a time left reported previously by <see cref="ReportBackAndContinue"> or <see cref="ReportBackAndBreak">. /// If it returned false, the time interval is not granted and it is illegal to report anything back using <see cref="ReportBackAndContinue"> or <see cref="ReportBackAndBreak">. /// </returns> public bool RequestTimeInterval(out TimeInterval interval) { this.Trace(); lock (innerLock) { DebugHelper.Assert(!sinkSideInProgress, "Requested a new time interval, but the previous one is still processed."); var result = true; if (!Enabled || changingEnabled) { // we test `changingEnabled` here to avoid starvation: // in order to change state of `Enabled` property the handle must not be latched, // so the operation blocks until `latchLevel` drops down to 0; // calling this method (`RequestTimeInterval`) when the handle is in a blocking state results // in latching it temporarily until `WaitUntilDone` is called; // this temporary latching/unlatching together with normal latching/unlatching in a short loop // can cause `latchLevel` to fluctuate from 1 to 2 never allowing the operation modifying `Enabled` to finish result = false; } else if (isBlocking && SourceSideActive) { // we check SourceSideActive here as otherwise unblocking will not succeed anyway DebugHelper.Assert(!grantPending, "New grant not expected when blocked."); this.Trace("Asking time source to unblock the time handle"); // latching here is to protect against disabling Enabled that would lead to making IsBlocking false while waiting for unblocking this handle Latch(); Monitor.Exit(innerLock); // it is necessary to leave `innerLock` since calling `UnblockHandle` could lead to a deadlock on `handles` collection var isHandleUnblocked = TimeSource.UnblockHandle(this); Monitor.Enter(innerLock); if (!isHandleUnblocked) { Unlatch(); this.Trace("Unblocking handle is not allowed, quitting"); result = false; } else { this.Trace("Handle unblocked"); // since we are latched here, latchLevel 1 means that the handle is not currently latched by anybody else // why? this is needed as we change the value of isBlocking - this should not happen when the handle is latched by another thread this.Trace("About to wait until the latch reduces to 1"); innerLock.WaitWhile(() => latchLevel > 1, "Waiting for reducing the latch to 1"); isBlocking = false; DebugHelper.Assert(!deferredUnlatch, "Unexpected value of deferredUnlatch"); deferredUnlatch = true; recentlyUnblocked = true; } } else if (!grantPending) { // wait until a new time interval is granted or this handle is disabled/deactivated innerLock.WaitWhile(() => !grantPending && Enabled && SourceSideActive, "Waiting for a time grant"); result = grantPending; } if (!result) { interval = TimeInterval.Empty; } else { interval = intervalGranted + timeResiduum; timeResiduum = TimeInterval.Empty; sinkSideInProgress = true; grantPending = false; } this.Trace($"{result}, {interval.Ticks}"); return(result); } }