the CreationKit Wiki

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

6,124 bytes removed ,  15:59, 27 January 2015
no edit summary
imported>Chesko
(Updated Thread section.)
imported>Chesko
 
(14 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|1128px|center|Fig. 3.1, 3.2]]
[[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 26: Line 49:
== Creation Kit ==
== Creation Kit ==


# '''Create Quest:''' Begin by opening the Creation Kit and creating a new Quest. We'll call our quest '''GuardPlacementQuest'''. Click OK to save and close the quest, then open it again (to prevent the CK from crashing). Make sure that "Start Game Enabled", "Run Once", "Warn on Alias Failure" and "Allow repeated stages" are unchecked. Click OK to close it again.
'''Create Quest:''' Begin by opening the Creation Kit and creating a new Quest. We'll call our quest '''GuardPlacementQuest'''. Click OK to save and close the quest, then open it again (to prevent the CK from crashing). Make sure that "Start Game Enabled", "Run Once", "Warn on Alias Failure" and "Allow repeated stages" are unchecked. Click OK to close it again.
# '''Create Future (Activator):''' Next, we want to create an object we will need later, called a <code>Future</code>. We'll get into what these do later. Open the Activator tree in the Creation Kit Object Window, and find ''''xMarkerActivator''''. Right click and Duplicate this object. Double-click the duplicate and rename it's Editor ID to identify it later; we'll call ours '''GuardPlacementFutureActivator'''.
# '''Create Anchor (Object Reference):''' We now want to create a "Future Anchor". This is an XMarker object reference that we will be placing in a far-off, unused cell. You can create your own blank cell, but '''AAADeleteWhenDoneTestJeremy''' is also a good candidate. Wherever you decide to place it, drag an XMarker Static from the Object Window of the Creation Kit into the Render Window and name the reference. We'll name ours '''GuardPlacementFutureAnchor'''. We'll use this to <code>PlaceAtMe()</code> Futures on this object later on.


<gallery widths="240px" heights="120px" perrow="3">
<gallery widths="240px" heights="200px" perrow="3">
Image:Multithreading-fig1-1.JPG|<b>Fig. 2.4</b>: <br> Create Quest
Image:Multithreading-fig1-1.JPG|<b>Fig. 3.3</b>: <br> Create Quest
Image:Multithreading-fig1-2.JPG|<b>Fig. 2.5</b>: <br> Create Future Activator
Image:Multithreading-fig1-3.JPG|<b>Fig. 2.6</b>: <br> Create Anchor
</gallery>
</gallery>


Line 101: Line 120:
;Called from Event OnGuardPlacement
;Called from Event OnGuardPlacement
function MoveGuardMarkerNearPlayer(ObjectReference akMarker)
function MoveGuardMarkerNearPlayer(ObjectReference akMarker)
;Move the marker away from the player a random distance and direction in 75.0 game unit increments
;Some difficult calculations, etc
Actor player = Game.GetPlayer()
Float A = player.GetAngleZ() + (Utility.RandomInt(1, 24) * 15.0)
Float YDist = math.Sin(A)
Float XDist = math.Cos(A)
XDist *= (Utility.RandomInt(1, 5) * 75.0)
YDist *= (Utility.RandomInt(1, 5) * 75.0)
akMarker.MoveTo(player, XDist, YDist)
EndFunction
EndFunction
   
   
Line 181: 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).
In the end, the function that we call in our Thread Manager will return a <code>Future</code>, which we can use to get our return value later.




<source lang="papyrus">
<source lang="papyrus">
scriptname GuardPlacementThreadManager extends Quest
scriptname GuardPlacementThreadManager extends Quest
 
Quest property GuardPlacementQuest auto
Quest property GuardPlacementQuest auto
{The name of the thread management quest.}
{The name of the thread management quest.}
 
Activator property GuardPlacementFutureActivator auto
{Our Future object.}
 
ObjectReference property GuardPlacementFutureAnchor auto
{Our Future Anchor object reference.}
 
Static property XMarker auto
Static property XMarker auto
{Something a thread needs; our threads don't declare their own properties.}
{Tedious to define properties in the threads and hook up in CK over and over, so define things we need here. MoveGuardMarkerNearPlayer() needs XMarkers.}


GuardPlacementThread01 thread01
GuardPlacementThread01 thread01
Line 205: Line 209:
GuardPlacementThread09 thread09
GuardPlacementThread09 thread09
GuardPlacementThread10 thread10
GuardPlacementThread10 thread10
 
Event OnInit()
Event OnInit()
     ;Register for the event that will start all threads
     ;Register for the event that will start all threads
Line 218: Line 222:
     thread10 = GuardPlacementQuest as GuardPlacementThread10
     thread10 = GuardPlacementQuest as GuardPlacementThread10
EndEvent
EndEvent
 
;The 'public-facing' function that our MagicEffect script will interact with.
;The 'public-facing' function that our MagicEffect script will interact with.
ObjectReference function PlaceConjuredGuardAsync(ActorBase akGuard)
function PlaceConjuredGuardAsync(ActorBase akGuard)
        int i = 0
    if !thread01.queued()
ObjectReference future
        thread01.get_async(akGuard, XMarker)
while !future
    elseif !thread02.queued()
if !thread01.queued()
thread02.get_async(akGuard, XMarker)
future = thread01.get_async(GuardPlacementFutureActivator, GuardPlacementFutureAnchor, akGuard, XMarker)
    ;...and so on
elseif !thread02.queued()
    elseif !thread09.queued()
future = thread02.get_async(GuardPlacementFutureActivator, GuardPlacementFutureAnchor, akGuard, XMarker)
        thread09.get_async(akGuard, XMarker)
...
    elseif !thread10.queued()
elseif !thread09.queued()
        thread10.get_async(akGuard, XMarker)
future = thread09.get_async(GuardPlacementFutureActivator, GuardPlacementFutureAnchor, akGuard, XMarker)
    else
elseif !thread10.queued()
;All threads are queued; start all threads, wait, and try again.
future = thread10.get_async(GuardPlacementFutureActivator, GuardPlacementFutureAnchor, akGuard, XMarker)
        wait_all()
else
        PlaceConjuredGuardAsync(akGuard)
;All threads are queued; start all threads, wait, and try again.
endif
                        wait_all()
endif
endWhile
 
return future
endFunction
endFunction
 
function wait_all()
function wait_all()
     RaiseEvent_OnGuardPlacement()
     RaiseEvent_OnGuardPlacement()
Line 267: Line 266:
endFunction
endFunction


;A helper function that can avert permanent thread failure if something goes wrong
;Create the ModEvent that will start this thread
function TryToUnlockThread(ObjectReference akFuture)
    bool success = false
    if thread01.has_future(akFuture)
        success = thread01.force_unlock()
    elseif thread02.has_future(akFuture)
        success = thread02.force_unlock()
    ;...and so on
    elseif thread09.has_future(akFuture)
        success = thread09.force_unlock()
    elseif thread10.has_future(akFuture)
        success = thread10.force_unlock()
    endif
   
    if !success
        debug.trace("Error: A thread has encountered an error and has become unresponsive.")
    else
        debug.trace("Warning: An unresponsive thread was successfully unlocked.")
    endif
endFunction
 
;Create the ModEvent that will start all threads
function RaiseEvent_OnGuardPlacement()
function RaiseEvent_OnGuardPlacement()
     int handle = ModEvent.Create("MyMod_OnGuardPlacement")
     int handle = ModEvent.Create("MyMod_OnGuardPlacement")
Line 300: Line 278:




The PlaceConjuredGuardAsync() function handles making sure that our work gets delegated to an available thread. The function then returns a <code>Future</code> once an available thread is found.
The PlaceConjuredGuardAsync() function handles making sure that our work gets delegated to an available thread.




Line 310: 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:


image here
[[File:Multithreading_quest_scripts.JPG|509px|center]]
 
 
== Back to the Future ==
 
'''Futures''' are [https://cloud.google.com/appengine/docs/python/ndb/futureclass a concept from parallel processing]. It can be thought of as a placeholder in lieu of your result until your result has arrived. Like the Google App Engine version that this was inspired by, when the Future is created, it will probably not have any results yet. Your script can store a <code>Future</code> and later call the <code>Future</code> object's <code>get_result()</code> function, which should return your results immediately.
 
 
{{InDepth|A few notes about Futures:
* Futures '''contain the result''' of a thread that has finished.
* Futures are lightweight Activator ObjectReferences placed in an unloaded cell.
* A <code>Future</code> is '''temporary''', and exists until the result is read, after which, the <code>Future</code> is destroyed. Make sure to save your results to your own variable if you will need them later, since the <code>Future</code> will no longer exist after calling <code>get_result()</code>. This keeps the number of ObjectReferences created under control, and helps prevent save game size bloat.
* <code>get_result()</code> is technically ''blocking'', meaning it waits until results are received from the thread, and then returns. However, since <code>wait_all()</code> waits for all threads to complete, there should be no reason you should have to wait on your results when calling this function, unless something went wrong.
* The result of a <code>Future</code> is the same as the result of any other function in Papyrus, and can return None, false, etc if an error is encountered. Code the result of a <code>Future</code> like you would the result of anything else and anticipate errors accordingly.
* Futures will attempt to unlock threads that have become unresponsive.}}
 
 
Let's create our Future:
 
 
<source lang="papyrus">
scriptname GuardPlacementFuture extends ObjectReference
 
Quest property GuardPlacementQuest auto
 
ObjectReference r
ObjectReference property result hidden
function set(ObjectReference akResult)
done = true
r = akResult
endFunction
endProperty
 
bool done = false
bool function done()
return done
endFunction
 
ObjectReference function get_result()
;Terminate the request after 10 seconds, or as soon as we have a result
int i = 0
while !done && i < 100
i += 1
utility.wait(0.1)
endWhile
RegisterForSingleUpdate(0.1)
       
        if i >= 100
                ;Our thread probably encountered an error and is locked up; we need to unlock it.
                (GuardPlacementQuest as GuardPlacementThreadManager).TryToUnlockThread(self as ObjectReference)
        endif
return r
endFunction
 
Event OnUpdate()
self.Disable()
self.Delete()
endEvent
</source>
 
 
This script should be '''compiled and attached to the Future Activator''' object we created earlier. After you've attached it, make sure to '''fill the properties.'''
 
 
{{ProTip|Note the Type of the result; this could be changed to any data type you need to return.}}
 
 
{{ProTip|As a best practice, only interface with the <code>Future</code> using its member functions, <code>done()</code> and <code>get_result()</code>.}}
 
 
=== Quick Detour: Revisiting the Thread Script ===
 
 
There was a line from our thread script that was commented out, because our Future script didn't exist yet:
 
<source lang="papyrus">
  ;(future as GuardPlacementFuture).result = result
</source>
 
Go back and uncomment this line and recompile the parent thread script. You don't need to recompile all of the children.
 
 
{{WarningBox|This is important! If you don't uncomment this line, your thread will never return results to the Future!}}




== Tying it All Together ==
== Tying it All Together ==


Now that we've created our Threads, our Thread Manager, and our Future script, 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.  
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 405: Line 301:
The flow using threads now is:
The flow using threads now is:


# Call an Async function on our Thread Manager, and store the <code>Future</code> it returns.
# Call an Async function on our Thread Manager.
# Later, call the <code>get_results()</code> function of the <code>Future</code> to retrieve the results.
# 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 421: Line 316:
ObjectReference Guard1
ObjectReference Guard1
ObjectReference Guard2
ObjectReference Guard2
...
;...and so on
ObjectReference Guard20
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
ObjectReference Guard1Future = threadmgr.PlaceConjuredGuardAsync(Guard)
threadmgr.PlaceConjuredGuardAsync(Guard)
ObjectReference Guard2Future = threadmgr.PlaceConjuredGuardAsync(Guard)
threadmgr.PlaceConjuredGuardAsync(Guard)
ObjectReference Guard3Future = threadmgr.PlaceConjuredGuardAsync(Guard)
;...and so on
;...and so on
ObjectReference Guard19Future = threadmgr.PlaceConjuredGuardAsync(Guard)
threadmgr.PlaceConjuredGuardAsync(Guard)
ObjectReference Guard20Future = threadmgr.PlaceConjuredGuardAsync(Guard)
threadmgr.PlaceConjuredGuardAsync(Guard)
 
threadmgr.wait_all()
                ;Begin working and wait for all of our threads to complete.
                threadmgr.wait_all()
 
;Collect the results
Guard1 = (Guard1Future as GuardPlacementFuture).get_result()
Guard2 = (Guard2Future as GuardPlacementFuture).get_result()
Guard3 = (Guard3Future as GuardPlacementFuture).get_result()
;...and so on
Guard19 = (Guard19Future as GuardPlacementFuture).get_result()
Guard20 = (Guard20Future as GuardPlacementFuture).get_result()
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.Disable()
DisableAndDelete(Guard1)
Guard1.Delete()
DisableAndDelete(Guard2)
;...and so on
                ;...and so on
Guard20.Disable()
DisableAndDelete(Guard9)
Guard20.Delete()
DisableAndDelete(Guard10)
endif
endif
endEvent
endEvent
</source>


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


Here, instead of doing the work in our script, we delegated the work to the Thread Manager, and stored the Futures that it returned to us. Then, we gathered the results using our Futures' <code>get_result()</code> function. We don't have to worry about our threads or the state of the Futures; those are freed up and cleared for us by the system.
ObjectReference myGuard = akGuard as ObjectReference


Even though all of the threads are working in parallel and might not finish at the same time, the <code>get_result()</code> function will wait until a result is available before returning. We can be sure that we will get the results even if they are processed out of order. For instance, if thread 2 completed before thread 1, calling the thread 1 Future's <code>get_result()</code> function will pause the script until a result is available. Then the thread 2 Future's result is gathered, and so on.
if !Guard1
Guard1 = myGuard
elseif !Guard2
Guard2 = myGuard
;...and so on
elseif !Guard9
Guard9 = myGuard
elseif !Guard10
Guard10 = myGuard
endif


== Notes on Futures ==
locked = false
endEvent


* Make sure to always call wait_all() after calling your asynchronous functions, or your threads '''will not start'''.
function DisableAndDelete(ObjectReference akReference)
akReference.Disable()
akReference.Delete()
endFunction
</source>


* We call <code>RegisterForModEvent()</code> on our Thread Manager's <code>OnInit()</code> block. Remember that this will need to be re-registered after '''every game load'''. You will need to define a Player Alias with an attached script that has an <code>OnPlayerLoadGame()</code> event defined that re-registers for this mod event. Any script attached to the quest with the threads can register for the event, and all threads will begin receiving those events.


* Be a good Papyrus and Skyrim citizen and read the results from your Futures as soon as you are able so that they can be disposed of. If Futures begin to pile up without being read and destroyed, save game bloat could occur.
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.


* If you are running operations in an always-on background script that you want to multithread, and you will always have the same number of results back, it may make more sense for you to implement a static set of Future references that are never destroyed that you continue to reuse. This would prevent the churn of Futures being created and destroyed and may lend itself to faster performance. Keep in mind that this would probably result in some data loss if your Futures are not read from regularly as the new results overwrite the old ones.
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/a/a5/TutorialExampleMod_Multithreading_Futures.zip Download Tutorial Example Plugin] - A fully functional, installable mod. Includes all tutorial files and source code.}}
{{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 492: Line 403:
In my personal experience, I saw greatly diminishing returns after 10 threads in this example.
In my personal experience, I saw greatly diminishing returns after 10 threads in this example.
* '''1 Thread:''' Avg. 3.4 seconds to complete
* '''1 Thread:''' Avg. 3.4 seconds to complete
* '''10 Threads:''' Avg. 1.4 seconds to complete
* '''10 Threads:''' Avg. 0.8 seconds to complete
* '''20 Threads:''' Avg. 1.1 seconds to complete
* '''20 Threads:''' Avg. 0.5 seconds to complete


This could be due to the fact that actors are more "expensive" to place than, say, a Static. In another mod, I saw that using 30 threads reduced my object placement time from 8.5 seconds to less than 1 on average. Obviously, profiling your script is critical to determine if your unique application would benefit the most from more or less threads (or threading at all).
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.
Anonymous user
Retrieved from "https://ck.uesp.net/wiki/Special:MobileDiff/8900...8915"