public class YieldInstruction
YieldInstruction is a unity specific class used in conjunction with Unity Coroutines.
Even though it is a Unity specific
class, it is listed on this API for informational purposes, as the IEnumerator<YieldInstruction>
return construct is used
throughout this API and it is helpful to have a page dedicated to explaining its use.
The IEnumerator<YieldInstruction> return construct is used extensively in the Streamable
Assets Manager, mainly in two ways.
The first is in public callable methods, primarily found in the
ComponentManager and
ActiveGrid classes.
With these methods, you will either need initialize them like other coroutines using
StartCoroutine, like so:
void Start()
{
StartCoroutine(SampleMethod());
}
or you will manually run them from a method that has been initialized via StartCoroutine.
Example:
void Start()
{
StartCoroutine(MyCoroutine());
}
IEnumerator MyCoroutine()
{
var en = SampleMethod();
while(en.MoveNext())
yield return en.Current;
}
The second technique is typically more useful, as it allows you to add additional
code within the while(en.MoveNext()) loop. It also
allows you to track when the enumerator finishes executing so that you can time other
actions with its completion.
It should also be noted that sometimes, you can run these methods in a single frame
(if absolutely necessary). Example:
void Start()
{
var en = SampleMethod();
while(en.MoveNext())
continue;
}
Do note, not all methods can be run this way!
The second way the IEnumerator<YieldInstruction> return construct is used in the Streamable
Assets Manager is as
the return type for overridable methods found in overridable classes, which you might
create to add custom behavior or logic.
These methods are run by the World class from a single StartCoroutine initialization
(unless otherwise noted), which reduces garbage generation.
You have two options for how to implement overridable methods that return IEnumerator<YieldInstruction>:
1) Use the normal yield return statements, where the return value is either null or
a derivative of YieldInstruction.
2) Use our garbage friendly ReusableEnumerators class.
For the first option, it should be noted that using yield return statements will result
in
auto generated iterators which will produce garbage. If using this construct, you
can either yield return null or a YieldInstruction.
Yield return null will cause the method to yield for a single frame and then resume
execution.
In addition, you can yield return a
WaitForSeconds object,
WaitForFixedUpdate object, or a new
Coroutine by using the
yield return StartCoroutine(CoroutineName()) construct.
For the second option, you will need to also make use of one of the
YieldEnumerator classes.
Use of these classes, as well as the ReusableEnumerators class, are only recommended for
advanced programmers, as the classes are not heavily documented and if they are not
used correctly, major issues can arise.
In fact, the ReusableEnumerators class is not documented in the website API, however
if you use it from code, you will find some information avaialable when referencing
it.