When telling kOS's CPU that it should yield, using the CPU.YieldProgram() method, you make a new instance of a derivative of this class to manage the decision of when it should resume again. kOS's CPU will repeatedly re-check the instance of this class whenever it wants to execute Opcodes, and only when this class says so will it resume execution of the Opcodes.

When you make a new instance of this class you should immediately "forget" it after it is passed to YieldProgram() (i.e. don't hold a reference to it.) If you call YieldProgram() again, it should always be a with a new instance of this class.

When you inherit from this class, you should store any data values that are part of the decision "am I done waiting" as members of this class, such that each new instance gets its own set of such fields and all instances can decide "am I done" indepentantly of each other.

The reason all the above instructions are relevant is that they allow the same Opcode, or Built-in Function to cause more than one YieldProgram to exist similtaneously from them.
(i.e. a Wait Opcode inside a function, and that function gets called from both the mainline code and a trigger. You want two different wait timers going for them even though they're coming from the exact same OpcodeWait instance in the program.)
YieldFinishedDetector Class Documentation
Example #1
0
File: CPU.cs Project: KSP-KOS/KOS 
 /// <summary>
 /// Call when you want to suspend execution of the Opcodes until some
 /// future condition becomes true.  The CPU will call yieldTracker.Begin()
 /// right away, and then after that call yieldTracker.IsFinished() again and
 /// again until it returns true.  Until IsFinished() returns true, the CPU
 /// will not advance any further into the program in its current "mode".
 /// Note that the CPU will track "trigger" and "mainline" code separately for
 /// this purpose.  Waiting in mainline code will still allow triggers to run.
 /// </summary>
 /// <param name="yieldTracker"></param>
 public void YieldProgram(YieldFinishedDetector yieldTracker)
 {
     switch (currentRunSection)
     {
         case Section.Main:
             mainYields.Add(yieldTracker);
             break;
         case Section.Trigger:
             triggerYields.Add(yieldTracker);
             break;
         default:
             // Should hypothetically be impossible unless we add more values to the enum.
             break;
     }
     yieldTracker.creationTimeStamp = currentTime;
     yieldTracker.Begin(shared);
 }
Example #2
0
 public void YieldProgram(YieldFinishedDetector yieldTracker)
 {
     throw new NotImplementedException();
 }