java
/
jMonkeyEngine-wiki
mirror of https://github.com/jMonkeyEngine/wiki.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523
							<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <title>Multithreading Optimization :: jMonkeyEngine Docs</title>
    <link rel="canonical" href="https://wiki.jmonkeyengine.org/docs/jme3/advanced/multithreading.html">
    <meta name="keywords" content="loop, game, performance, state, states, documentation">
    <meta name="generator" content="Antora 2.3.3">
    <link rel="stylesheet" href="../../../_/css/site.css">
<meta property="og:image" content="https://mitm001.github.io/docs.jmonkeyengine.org/_/img/iconx128.png">
<meta property="og:description" content="Multithreading Optimization">
<meta property="og:title" content="jMonkeyEngine Docs">
<link rel="icon" href="../../../_/img/favicon.ico" type="image/x-icon">
  </head>
  <body class="article">
<header class="header">
  <nav class="navbar">
    <div class="navbar-brand">
      <a class="navbar-item" href="https://wiki.jmonkeyengine.org">
        <img alt="" src="../../../_/img/iconx128.png" width="32" type="image/x-icon" style="margin-right:16px">
        jMonkeyEngine Docs
        </a>
      <button class="navbar-burger" data-target="topbar-nav">
        <span></span>
        <span></span>
        <span></span>
      </button>
    </div>
    <div id="topbar-nav" class="navbar-menu">
      <div class="navbar-end">
        <div class="navbar-item theme-switch-wrapper">
          <label class="theme-switch" for="checkbox">
            <input type="checkbox" id="checkbox" />
            <div class="slider round"></div>
          </label>
          <p class="navlabel">Dark Mode</p>
        </div>
        <a class="navbar-item" href="https://github.com/jmonkeyengine/wiki">Github</a>
      </div>
    </div>
  </nav>
</header>
<div class="body">
<div class="nav-container" data-component="docs" data-version="master">
  <aside class="nav">
    <div class="panels">
<div class="nav-panel-menu is-active" data-panel="menu">
  <nav class="nav-menu">
    <h3 class="title"><a href="../../documentation.html">Docs</a></h3>
<ul class="nav-list">
  <li class="nav-item" data-depth="0">
<ul class="nav-list">
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../../documentation.html">Getting Started</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="https://javadoc.jmonkeyengine.org/v3.3.2-stable">JavaDoc</a>
  </li>
  <li class="nav-item" data-depth="1">
    <button class="nav-item-toggle"></button>
    <a class="nav-link" href="../../jme3.html">jMonkeyEngine 3</a>
<ul class="nav-list">
  <li class="nav-item" data-depth="2">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">Beginner Tutorials</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_simpleapplication.html">Hello SimpleApplication</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_node.html">Hello Node</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_asset.html">Hello Asset</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_main_event_loop.html">Hello Main Event Loop</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_input_system.html">Hello Input System</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_material.html">Hello Material</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_animation.html">Hello Animation</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_picking.html">Hello Picking</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_collision.html">Hello Collision</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_terrain.html">Hello Terrain</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_audio.html">Hello Audio</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_effects.html">Hello Effects</a>
  </li>
  <li class="nav-item" data-depth="3">
    <a class="nav-link" href="../beginner/hello_physics.html">Hello Physics</a>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="2">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">Intermediate Tutorials</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="3">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">Concepts</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../intermediate/best_practices.html">Best Practices</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../intermediate/simpleapplication.html">Simple Application</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../features.html">Features</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../intermediate/optimization.html">Optimization</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../faq.html">FAQ</a>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="3">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">Math Concepts</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../math_for_dummies.html">Math For Dummies</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../intermediate/math.html">Math</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../math.html">More Math</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../rotate.html">Rotate</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../math_video_tutorials.html">Math Video Tutorials</a>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="3">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">3D Graphics Concepts</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../intermediate/multi-media_asset_pipeline.html">Multi-Media Asset Pipeline</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../scenegraph_for_dummies.html">Scenegraph for Dummies</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../beginner/hellovector.html">Hello Vector</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../terminology.html">Terminology</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../intermediate/how_to_use_materials.html">How to Use Materials</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../intermediate/transparency_sorting.html">Transparency and Sorting</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../external/blender.html">Importing from Blender</a>
  </li>
  <li class="nav-item" data-depth="4">
    <a class="nav-link" href="../external/3dsmax.html">Importing from 3DS Max</a>
  </li>
</ul>
  </li>
</ul>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../../logo.html">Logo Usage</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../../bsd_license.html">License</a>
  </li>
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../../github_tips.html">Github Tips</a>
  </li>
</ul>
  </li>
  <li class="nav-item" data-depth="0">
    <button class="nav-item-toggle"></button>
    <span class="nav-text">SDK</span>
<ul class="nav-list">
  <li class="nav-item" data-depth="1">
    <a class="nav-link" href="../../sdk.html">jMonkeyEngine SDK</a>
  </li>
</ul>
  </li>
</ul>
  </nav>
</div>
<div class="nav-panel-explore" data-panel="explore">
  <div class="context">
    <span class="title">Docs</span>
    <span class="version">master</span>
  </div>
  <ul class="components">
    <li class="component is-current">
      <span class="title">Docs</span>
      <ul class="versions">
        <li class="version is-current is-latest">
          <a href="../../documentation.html">master</a>
        </li>
      </ul>
    </li>
    <li class="component">
      <span class="title">Wiki UI</span>
      <ul class="versions">
        <li class="version is-latest">
          <a href="../../../wiki-ui/index.html">master</a>
        </li>
      </ul>
    </li>
  </ul>
</div>
    </div>
  </aside>
</div>
<main class="article">
<div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
<nav class="breadcrumbs" aria-label="breadcrumbs">
  <ul>
    <li><a href="../../documentation.html">Docs</a></li>
    <li><a href="multithreading.html">Multithreading Optimization</a></li>
  </ul>
</nav>
  <div class="edit-this-page"><a href="https://github.com/jMonkeyEngine/wiki/edit/master/docs/modules/ROOT/pages/jme3/advanced/multithreading.adoc">Edit this Page</a></div>
  </div>
  <div class="content">
<article class="doc">
<h1 class="page">Multithreading Optimization</h1>
<div class="sect1">
<h2 id="the-jme3-threading-model"><a class="anchor" href="#the-jme3-threading-model"></a>The jME3 Threading Model</h2>
<div class="sectionbody">
<div class="paragraph">
<p>jME3 is similar to Swing in that, for speed and efficiency, all changes to the scene graph must be made in a single update thread. If you make changes only in Control.update(), AppState.update(), or SimpleApplication.simpleUpdate(), this will happen automatically.  However, if you pass work to another thread, you may need to pass results back to the main jME3 thread so that scene graph changes can take place there.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public void rotateGeometry(final Geometry geo, final Quaternion rot) {
    mainApp.enqueue(new Callable&lt;Spatial&gt;() {
        public Spatial call() throws Exception {
            return geo.rotate(rot);
        }
    });
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>This example does not fetch the returned value by calling <code>get()</code> on the Future object returned from <code>enqueue()</code>. This means that the example method <code>rotateGeometry()</code> will return immediately and will not wait for the rotation to be processed before continuing.</p>
</div>
<div class="paragraph">
<p>If the processing thread needs to wait or needs the return value then <code>get()</code> or the other methods in the returned Future object such as <code>isDone()</code> can be used.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>First, make sure you know what <a href="application_states.html" class="page">Application States</a> and <a href="custom_controls.html" class="page">Custom Controls</a> are.</p>
</div>
<div class="paragraph">
<p>More complex games may feature complex mathematical operations or artificial intelligence calculations (such as path finding for several NPCs). If you make many time-intensive calls on the same thread (in the update loop), they will block one another, and thus slow down the game to a degree that makes it unplayable. If your game requires long running tasks, you should run them concurrently on separate threads, which speeds up the application considerably.</p>
</div>
<div class="paragraph">
<p>Often multithreading means having separate detached logical loops going on in parallel, which communicate about their state. (For example, one thread for AI, one Sound, one Graphics). However we recommend to use a global update loop for game logic, and do multithreading within that loop when it is appropriate. This approach scales way better to multiple cores and does not break up your code logic.</p>
</div>
<div class="paragraph">
<p>Effectively, each for-loop in the main update loop might be a chance for multithreading, if you can break it up into self-contained tasks.</p>
</div>
<div class="sect2">
<h3 id="java-multithreading"><a class="anchor" href="#java-multithreading"></a>Java Multithreading</h3>
<div class="paragraph">
<p>The java.util.concurrent package provides a good foundation for multithreading and dividing work into tasks that can be executed concurrently (hence the name). The three basic components are the Executor (supervises threads), Callable Objects (the tasks), and Future Objects (the result). You can <a href="http://download.oracle.com/javase/tutorial/essential/concurrency/">read about the concurrent package more here</a>, I will give just a short introduction.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A Callable is one of the classes that gets executed on a thread in the Executor. The object represents one of several concurrent tasks (e.g, one NPC&#8217;s path finding task). Each Callable is started from the updateloop by calling a method named <code>call()</code>.</p>
</li>
<li>
<p>The Executor is one central object that manages all your Callables. Every time you schedule a Callable in the Executor, the Executor returns a Future object for it.</p>
</li>
<li>
<p>A Future is an object that you use to check the status of an individual Callable task. The Future also gives you the return value in case one is returned.</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="multithreading-in-jme3"><a class="anchor" href="#multithreading-in-jme3"></a>Multithreading in jME3</h3>
<div class="paragraph">
<p>So how do we implement multithreading in jME3?</p>
</div>
<div class="paragraph">
<p>Let&#8217;s take the example of a Control that controls an NPC Spatial. The NPC Control has to compute a lengthy pathfinding operation for each NPC. If we would execute the operations directly in the simpleUpdate() loop, it would block the game  each time a NPC wants to move from A to B. Even if we move this behaviour into the update() method of a dedicated NPC Control, we would still get annoying freeze frames, because it still runs on the same update loop thread.</p>
</div>
<div class="paragraph">
<p>To avoid slowdown, we decide to keep the pathfinding operations in the NPC Control, <em>but execute it on another thread</em>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="executor"><a class="anchor" href="#executor"></a>Executor</h2>
<div class="sectionbody">
<div class="paragraph">
<p>You create the executor object in a global AppState (or the initSimpleApp() method), in any case in a high-level place where multiple controls can access it.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">/* This constructor creates a new executor with a core pool size of 4. */
ScheduledThreadPoolExecutor executor = new ScheduledThreadPoolExecutor(4);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Pool size means the executor will keep four threads alive at any time. Having more threads in the pool means that more tasks can run concurrently. But a bigger pool only results in a speed gain if the PC can handle it! Allocating a pool  that is uselessly large just wastes memory, so you need to find a good compromise: About the same to double the size of the number of cores in the computer makes sense.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Executor needs to be shut down when the application ends, in order to make the process die properly
In your simple application you can override the destroy method and shutdown the executor:</p>
</div>
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">    @Override
    public void destroy() {
        super.destroy();
        executor.shutdown();
    }</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="control-class-fields"><a class="anchor" href="#control-class-fields"></a>Control Class Fields</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In the NPC Control, we create the individual objects that the thread manipulates. In our example case (the pathfinding control), the task is about locations and path arrays, so we need the following variables:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-Java hljs" data-lang="Java">//The vector to store the desired location in:
Vector3f desiredLocation = new Vector3f();
//The MyWayList object that contains the result waylist:
MyWayList wayList = null;
//The future that is used to check the execution status:
Future future = null;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Here we also created the Future variable to track the state of this task.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="control-update-method"><a class="anchor" href="#control-update-method"></a>Control Update() Method</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Next let&#8217;s look at the update() call of the Control where the time-intensive task starts. In our example, the task is the <code>findWay</code> Callable (which contains the pathfinding process). So instead of spelling out the pathfinding process  in the Control&#8217;s update() loop, we start the process via <code>future = executor.submit(findWay);</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public void update(float tpf) {
    try{
        //If we have no waylist and not started a callable yet, do so!
        if(wayList == null &amp;&amp; future == null){
            //set the desired location vector, after that we should not modify it anymore
            //because it's being accessed on the other thread!
            desiredLocation.set(getGoodNextLocation());
            //start the callable on the executor
            future = executor.submit(findWay);    //  Thread starts!
        }
        //If we have started a callable already, we check the status
        else if(future != null){
            //Get the waylist when its done
            if(future.isDone()){
                wayList = future.get();
                future = null;
            }
            else if(future.isCancelled()){
                //Set future to null. Maybe we succeed next time...
                future = null;
            }
        }
    }
    catch(Exception e){
      Exceptions.printStackTrace(e);
    }
    if(wayList != null){
        //.... Success! Let's process the wayList and move the NPC...
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note how this logic makes its decision based on the Future object.</p>
</div>
<div class="paragraph">
<p>Remember not to mess with the class fields after starting the thread, because they are being accessed and modified on the new thread. In more obvious terms: You cannot change the “desired location of the NPC while the path finder is calculating a different path. You have to cancel the current Future first.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="the-callable"><a class="anchor" href="#the-callable"></a>The Callable</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The next code sample shows the Callable that is dedicated to performing the long-running task (here, wayfinding). This is the task that used to block the rest of the application, and is now executed on a thread of its own. You implement the task in the Callable always in an inner method named <code>call()</code>.</p>
</div>
<div class="paragraph">
<p>The task code in the Callable should be self-contained! It should not write or read any data of objects that are managed by the scene graph or OpenGL thread directly. Even reading locations of Spatials can be problematic! So ideally all data that is needed for the wayfinding process should be available to the new thread when it starts already, possibly in a cloned version so no concurrent access to the data happens.</p>
</div>
<div class="paragraph">
<p>In reality, you might need access to the game state. If you must read or write a current state from the scene graph, you must have a clone of the data in your thread. There are only two ways:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Use the execution queue <code>application.enqueue()</code> to create a sub-thread that clones the info. Only disadvantage is, it may be slower.<br>
The example below gets the <code>Vector3f location</code> from the scene object <code>mySpatial</code> using this way.</p>
</li>
<li>
<p>Create a separate World class that allows safe access to its data via synchronized methods to access the scene graph. Alternatively it can also internally use <code>application.enqueue()</code>.<br>
The following example gets the object <code>Data data = myWorld.getData();</code> using this way.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>These two ways are thread-safe, they don&#8217;t mess up the game logic, and keep the Callable code readable.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// A self-contained time-intensive task:
private Callable&lt;MyWayList&gt; findWay = new Callable&lt;MyWayList&gt;(){
    public MyWayList call() throws Exception {

        //Read or write data from the scene graph -- via the execution queue:
        Vector3f location = application.enqueue(new Callable&lt;Vector3f&gt;() {
            public Vector3f call() throws Exception {
                //we clone the location so we can use the variable safely on our thread
                return mySpatial.getLocalTranslation().clone();
            }
        }).get();

        // This world class allows safe access via synchronized methods
        Data data = myWorld.getData();

        //... Now process data and find the way ...

        return wayList;
    }
};</code></pre>
</div>
</div>
<div class="sect2">
<h3 id="useful-links"><a class="anchor" href="#useful-links"></a>Useful Links</h3>
<div class="paragraph">
<p>High level description which describes how to manage the game state and the rendering in different threads:<br>
<a href="http://jahej.com/alt/2011_07_03_threading-and-your-game-loop.html">Threading and your game loop</a>.<br>
A C++ example can be found at:<br>
<a href="http://gamasutra.com/blogs/AndreaMagnorsky/20130527/193087/Multithreading_rendering_in_a_game_engine_with_CDouble_buffer_implementation.php">Multithreading-rendering in a game engine with CDouble buffer implementation</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="conclusion"><a class="anchor" href="#conclusion"></a>Conclusion</h3>
<div class="paragraph">
<p>The cool thing about this approach is that every entity creates one self-contained Callable for the Executor, and they are all executed in parallel. In theory, you can have one thread per entity without changing anything else but the settings of the executor.</p>
</div>
</div>
</div>
</div>
</article>
<aside class="toc sidebar" data-title="Contents" data-levels="2">
  <div class="toc-menu"></div>
</aside>
  </div>
</main>
</div>
<footer class="footer">
  <p>Copyright 2020 jMonkeyEngine Wiki Contributors. Licensed BSD-3.</p>
</footer>
<script src="../../../_/js/site.js"></script>
<script async src="../../../_/js/vendor/highlight.js"></script>
  </body>
</html>