Difference between revisions of "Creating Multithreaded Skyrim Mods Part 3 - Callbacks"
Creating Multithreaded Skyrim Mods Part 3 - Callbacks (edit)
Revision as of 15:59, 27 January 2015
, 15:59, 27 January 2015no edit summary
imported>Chesko |
imported>Chesko |
||
(10 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
[[Category: Tutorials]] | [[Category: Tutorials]] | ||
[[Category: Community Tutorials]] | |||
{{Tutorial Index | {{Tutorial Index | ||
Line 9: | Line 10: | ||
We will be implementing a multithreaded solution to our example problem (a Conjuration mod that spawns many actors) using the '''Callback pattern'''. | We will be implementing a multithreaded solution to our example problem (a Conjuration mod that spawns many actors) using the '''Callback pattern'''. | ||
{{NewFeature| [http://www.creationkit.com/images/b/bd/TutorialExampleMod_Multithreading_Callbacks.zip Download Tutorial Example Plugin] - A fully functional, installable mod. Includes all tutorial files and source code.}} | |||
== Pattern Overview == | == Pattern Overview == | ||
To recap the Pros and Cons of this approach: | |||
==== Callback Pros ==== | |||
* '''Push-based:''' Using callbacks is a ''push'' pattern, where results are returned to you as soon as they're available instead of having to request them. | |||
* '''Anyone can access results:''' The results of a thread are available to anyone who registered for the event that returns them. | |||
* '''Results received without delays:''' Unlike Futures, you do not have to block your script pending results being available. Just register for the appropriate event and react to it. | |||
* '''No polling:''' You no longer have to potentially poll for whether or not your results are ready. | |||
* '''Easier to understand:''' The concepts in a Callback pattern are nothing new to anyone who knows how to use Mod Events. | |||
* '''Easier to implement:''' Their are comparatively fewer things to deal with when using a Callback pattern. | |||
* '''Less overhead (faster):''' Using a callback pattern can be a bit faster than a Future-based approach. | |||
==== Callback Cons ==== | |||
* '''...Anyone can access results:''' You have no control over who is able to consume your results. | |||
* '''No control when results are retrieved:''' You have no control over when a result will be retrieved, or in what order. You must be able to react to the result events that are raised, and you must assume that threads can finish in any order. | |||
* '''More difficult to trace execution order:''' A callback pattern can make the script flow more difficult to follow and debug, since the function where a thread is started and the event that it returns results to will be in two (or more) different places. | |||
* '''Locks required:''' Locks are required if you have two threads that may write to the same variable. | |||
* '''Requires more state management:''' You can receive result callbacks at any time, which may make it necessary for you to re-evaluate the script's current state each time you receive one, depending on your application. | |||
Here is a diagram of how the Callback pattern works. | Here is a diagram of how the Callback pattern works. | ||
[[File:Multithreading_fig3_1.png| | [[File:Multithreading_fig3_1.png|1056px|center|Fig. 3.1, 3.2]] | ||
Above, you can see that the sequence is: | Above, you can see that the sequence is: | ||
Line 29: | Line 52: | ||
<gallery widths="240px" heights="200px" perrow="3"> | <gallery widths="240px" heights="200px" perrow="3"> | ||
Image:Multithreading-fig1-1.JPG|<b>Fig. | Image:Multithreading-fig1-1.JPG|<b>Fig. 3.3</b>: <br> Create Quest | ||
</gallery> | </gallery> | ||
Line 170: | Line 193: | ||
Declare any properties that your threads will need in this script; the threads themselves will not have properties defined (since this would be tedious to hook up in the Creation Kit for each thread). | Declare any properties that your threads will need in this script; the threads themselves will not have properties defined (since this would be tedious to hook up in the Creation Kit for each thread). | ||
Line 205: | Line 226: | ||
function PlaceConjuredGuardAsync(ActorBase akGuard) | function PlaceConjuredGuardAsync(ActorBase akGuard) | ||
if !thread01.queued() | if !thread01.queued() | ||
thread01.get_async(akGuard, XMarker) | thread01.get_async(akGuard, XMarker) | ||
elseif !thread02.queued() | elseif !thread02.queued() | ||
thread02.get_async(akGuard, XMarker) | thread02.get_async(akGuard, XMarker) | ||
;...and so on | ;...and so on | ||
elseif !thread09.queued() | elseif !thread09.queued() | ||
thread09.get_async(akGuard, XMarker) | thread09.get_async(akGuard, XMarker) | ||
elseif !thread10.queued() | elseif !thread10.queued() | ||
thread10.get_async(akGuard, XMarker) | thread10.get_async(akGuard, XMarker) | ||
else | else | ||
Line 271: | Line 288: | ||
'''Compile and attach''' this script to your GuardPlacementQuest. then, double-click the Thread Manager script and '''fill the properties'''. Once you've done that, your quest's script section should look something like this: | '''Compile and attach''' this script to your GuardPlacementQuest. then, double-click the Thread Manager script and '''fill the properties'''. Once you've done that, your quest's script section should look something like this: | ||
[[File:Multithreading_quest_scripts.JPG|509px|center]] | |||
== Tying it All Together == | == Tying it All Together == | ||
Now that we've created our Threads | Now that we've created our Threads and our Thread Manager, we can start to put them to work. Since we aren't calling the functions we want to execute directly, we need to change how we do things slightly. | ||
The previous execution flow was: | The previous execution flow was: | ||
Line 284: | Line 301: | ||
The flow using threads now is: | The flow using threads now is: | ||
# Call an Async function on our Thread Manager | # Call an Async function on our Thread Manager. | ||
# | # Handle return events as they are raised and store our results. | ||
In our original ActiveMagicEffect script, we did all of our MoveGuardMarkerNearPlayer() and PlaceAtMe() calls in a row, getting a series of Actor references for our guards in return. We're going to modify that slightly to use our shiny new threaded placement system. | |||
In our original ActiveMagicEffect script, we did all of our MoveGuardMarkerNearPlayer() and PlaceAtMe() calls in a row, getting a series of Actor references for our guards in return. We're going to modify that slightly to use our shiny new threaded placement system | |||
<source lang="papyrus"> | <source lang="papyrus"> | ||
scriptname SummonArmy extends ActiveMagicEffect | scriptname SummonArmy extends ActiveMagicEffect | ||
Quest property GuardPlacementQuest auto | Quest property GuardPlacementQuest auto | ||
{We need a reference to our quest with the threads and Thread Manager defined.} | {We need a reference to our quest with the threads and Thread Manager defined.} | ||
Line 300: | Line 316: | ||
ObjectReference Guard1 | ObjectReference Guard1 | ||
ObjectReference Guard2 | ObjectReference Guard2 | ||
... | ;...and so on | ||
ObjectReference | ObjectReference Guard9 | ||
ObjectReference Guard10 | |||
Event OnEffectStart(Actor akTarget, Actor akCaster) | Event OnEffectStart(Actor akTarget, Actor akCaster) | ||
if akCaster == Game.GetPlayer() | if akCaster == Game.GetPlayer() | ||
;Cast the Quest as our Thread Manager and store it | ;Cast the Quest as our Thread Manager and store it | ||
GuardPlacementThreadManager threadmgr = GuardPlacementQuest as GuardPlacementThreadManager | GuardPlacementThreadManager threadmgr = GuardPlacementQuest as GuardPlacementThreadManager | ||
;Register for the callback event | |||
RegisterForModEvent("MyMod_GuardPlacementCallback", "GuardPlacementCallback") | |||
;Call PlaceConjuredGuardAsync for each Guard and store the returned Future | ;Call PlaceConjuredGuardAsync for each Guard and store the returned Future | ||
threadmgr.PlaceConjuredGuardAsync(Guard) | |||
threadmgr.PlaceConjuredGuardAsync(Guard) | |||
;...and so on | ;...and so on | ||
threadmgr.PlaceConjuredGuardAsync(Guard) | |||
threadmgr.PlaceConjuredGuardAsync(Guard) | |||
threadmgr.wait_all() | |||
endif | endif | ||
endEvent | endEvent | ||
Event OnEffectFinish(Actor akTarget, Actor akCaster) | Event OnEffectFinish(Actor akTarget, Actor akCaster) | ||
if akCaster == Game.GetPlayer() | if akCaster == Game.GetPlayer() | ||
Guard1 | DisableAndDelete(Guard1) | ||
DisableAndDelete(Guard2) | |||
;...and so on | |||
DisableAndDelete(Guard9) | |||
DisableAndDelete(Guard10) | |||
endif | endif | ||
endEvent | endEvent | ||
bool locked = false | |||
Event GuardPlacementCallback(Form akGuard) | |||
;A spin lock is required here to prevent us from writing two guards to the same variable | |||
while locked | |||
Utility.wait(0.1) | |||
endWhile | |||
locked = true | |||
ObjectReference myGuard = akGuard as ObjectReference | |||
if !Guard1 | |||
Guard1 = myGuard | |||
elseif !Guard2 | |||
Guard2 = myGuard | |||
;...and so on | |||
elseif !Guard9 | |||
Guard9 = myGuard | |||
elseif !Guard10 | |||
Guard10 = myGuard | |||
endif | |||
locked = false | |||
endEvent | |||
function DisableAndDelete(ObjectReference akReference) | |||
akReference.Disable() | |||
akReference.Delete() | |||
endFunction | |||
</source> | |||
Here, instead of doing the work in our script, registered for a callback Mod Event and delegated the work to the Thread Manager. We then called the Thread Manager's <code>wait_all()</code> function to make sure every thread has completed before continuing. Our return values are handed to us when the <code>GuardPlacementCallback()</code> event is raised. | |||
You'll notice that our callback event employs a spin lock. This is very important, since it is possible for two callback events to accidentally write to the same variable using this pattern. | |||
== Notes on Callbacks == | |||
* You can create as many threads as you want, but I wouldn't recommend more than 10 or so. It depends on your needs, the strain each thread places on the Papyrus VM, and how quickly you need your results. | * You can create as many threads as you want, but I wouldn't recommend more than 10 or so. It depends on your needs, the strain each thread places on the Papyrus VM, and how quickly you need your results. | ||
* If you need to perform a set of actions that are not all the same, the Thread Manager might not be best for you. You may want to create different thread base scripts purpose-built for your various tasks and then call their get_async() functions directly, blocking on <code>queued()</code> until they're available. You can still run many different tasks concurrently this way, even if they're not the same. | * If you need to perform a set of actions that are not all the same, the Thread Manager might not be best for you. You may want to create different thread base scripts purpose-built for your various tasks and then call their get_async() functions directly, blocking on <code>queued()</code> until they're available. You can still run many different tasks concurrently this way, even if they're not the same. | ||
== Playing the Example Plugin == | == Playing the Example Plugin == | ||
{{NewFeature| [http://www.creationkit.com/images/ | {{NewFeature| [http://www.creationkit.com/images/b/bd/TutorialExampleMod_Multithreading_Callbacks.zip Download Tutorial Example Plugin] - A fully functional, installable mod. Includes all tutorial files and source code.}} | ||
The example plugin can be installed using a mod manager, or by dragging all of the zipped files into the Skyrim\Data directory of your installation. | The example plugin can be installed using a mod manager, or by dragging all of the zipped files into the Skyrim\Data directory of your installation. | ||
Line 374: | Line 406: | ||
* '''20 Threads:''' Avg. 0.5 seconds to complete | * '''20 Threads:''' Avg. 0.5 seconds to complete | ||
Profiling your script is critical to determine if your unique application would benefit the most from more or less threads (or threading at all). | |||
Your experience and times may differ based on your current load order and system performance. Give it a try and see what results you obtain. | Your experience and times may differ based on your current load order and system performance. Give it a try and see what results you obtain. |