2 |

3 |
4 |
Fork of Paper which adds regionised multithreading to the dedicated server.
5 |
6 |
7 | ## Overview
8 |
9 | Folia groups nearby loaded chunks to form an "independent region."
10 | See [the PaperMC documentation](https://docs.papermc.io/folia/reference/region-logic) for exact details on how Folia
11 | will group nearby chunks.
12 | Each independent region has its own tick loop, which is ticked at the
13 | regular Minecraft tickrate (20TPS). The tick loops are executed
14 | on a thread pool in parallel. There is no main thread anymore,
15 | as each region effectively has its own "main thread" that executes
16 | the entire tick loop.
17 |
18 | For a server with many spread out players, Folia will create many
19 | spread out regions and tick them all in parallel on a configurable sized
20 | threadpool. Thus, Folia should scale well for servers like this.
21 |
22 | Folia is also its own project, this will not be merged into Paper
23 | for the foreseeable future.
24 |
25 | A more detailed but abstract overview: [Project overview](https://docs.papermc.io/folia/reference/overview).
26 |
27 | ## FAQ
28 |
29 | ### What server types can benefit from Folia?
30 | Server types that naturally spread players out,
31 | like skyblock or SMP, will benefit the most from Folia. The server
32 | should have a sizeable player count, too.
33 |
34 | ### What hardware will Folia run best on?
35 | Ideally, at least 16 _cores_ (not threads).
36 |
37 | ### How to best configure Folia?
38 | First, it is recommended that the world is pre-generated so that the number
39 | of chunk system worker threads required is reduced greatly.
40 |
41 | The following is a _very rough_ estimation based off of the testing
42 | done before Folia was released on the test server we ran that
43 | had ~330 players peak. So, it is not exact and will require further tuning -
44 | just take it as a starting point.
45 |
46 | The total number of cores on the machine available should be
47 | taken into account. Then, allocate threads for:
48 | - netty IO :~4 per 200-300 players
49 | - chunk system io threads: ~3 per 200-300 players
50 | - chunk system workers if pre-generated, ~2 per 200-300 players
51 | - There is no best guess for chunk system workers if not pre-generated, as
52 | on the test server we ran we gave 16 threads but chunk generation was still
53 | slow at ~300 players.
54 | - GC Settings: ???? But, GC settings _do_ allocate concurrent threads, and you need
55 | to know exactly how many. This is typically through the `-XX:ConcGCThreads=n` flag. Do not
56 | confuse this flag with `-XX:ParallelGCThreads=n`, as parallel GC threads only run when
57 | the application is paused by GC and as such should not be taken into account.
58 |
59 | After all of that allocation, the remaining cores on the system until 80%
60 | allocation (total threads allocated < 80% of cpus available) can be
61 | allocated to tickthreads (under global config, threaded-regions.threads).
62 |
63 | The reason you should not allocate more than 80% of the cores is due to the
64 | fact that plugins or even the server may make use of additional threads
65 | that you cannot configure or even predict.
66 |
67 | Additionally, the above is all a rough guess based on player count, but
68 | it is very likely that the thread allocation will not be ideal, and you
69 | will need to tune it based on usage of the threads that you end up seeing.
70 |
71 | ## Plugin compatibility
72 |
73 | There is no more main thread. I expect _every_ single plugin
74 | that exists to require _some_ level of modification to function
75 | in Folia. Additionally, multithreading of _any kind_ introduces
76 | possible race conditions in plugin held data - so, there are bound
77 | to be changes that need to be made.
78 |
79 | So, have your expectations for compatibility at 0.
80 |
81 | ## API plans
82 |
83 | Currently, there is a lot of API that relies on the main thread.
84 | I expect basically zero plugins that are compatible with Paper to
85 | be compatible with Folia. However, there are plans to add API that
86 | would allow Folia plugins to be compatible with Paper.
87 |
88 | For example, the Bukkit Scheduler. The Bukkit Scheduler inherently
89 | relies on a single main thread. Folia's RegionScheduler and Folia's
90 | EntityScheduler allow scheduling of tasks to the "next tick" of whatever
91 | region "owns" either a location or an entity. These could be implemented
92 | on regular Paper, except they schedule to the main thread - in both cases,
93 | the execution of the task will occur on the thread that "owns" the
94 | location or entity. This concept applies in general, as the current Paper
95 | (single threaded) can be viewed as one giant "region" that encompasses
96 | all chunks in all worlds.
97 |
98 | It is not yet decided whether to add this API to Paper itself directly
99 | or to Paperlib.
100 |
101 | ### The new rules
102 |
103 | First, Folia breaks many plugins. To aid users in figuring out which
104 | plugins work, only plugins that have been explicitly marked by the
105 | author(s) to work with Folia will be loaded. By placing
106 | "folia-supported: true" into the plugin's plugin.yml, plugin authors
107 | can mark their plugin as compatible with regionised multithreading.
108 |
109 | The other important rule is that the regions tick in _parallel_, and not
110 | _concurrently_. They do not share data, they do not expect to share data,
111 | and sharing of data _will_ cause data corruption.
112 | Code that is running in one region under no circumstance can
113 | be accessing or modifying data that is in another region. Just
114 | because multithreading is in the name, it doesn't mean that everything
115 | is now thread-safe. In fact, there are only a _few_ things that were
116 | made thread-safe to make this happen. As time goes on, the number
117 | of thread context checks will only grow, even _if_ it comes at a
118 | performance penalty - _nobody_ is going to use or develop for a
119 | server platform that is buggy as hell, and the only way to
120 | prevent and find these bugs is to make bad accesses fail _hard_ at the
121 | source of the bad access.
122 |
123 | This means that Folia compatible plugins need to take advantage of
124 | API like the RegionScheduler and the EntityScheduler to ensure
125 | their code is running on the correct thread context.
126 |
127 | In general, it is safe to assume that a region owns chunk data
128 | in an approximate 8 chunks from the source of an event (i.e. player
129 | breaks block, can probably access 8 chunks around that block). But,
130 | this is not guaranteed - plugins should take advantage of upcoming
131 | thread-check API to ensure correct behavior.
132 |
133 | The only guarantee of thread-safety comes from the fact that a
134 | single region owns data in certain chunks - and if that region is
135 | ticking, then it has full access to that data. This data is
136 | specifically entity/chunk/poi data, and is entirely unrelated
137 | to **ANY** plugin data.
138 |
139 | Normal multithreading rules apply to data that plugins store/access
140 | their own data or another plugin's - events/commands/etc. are called
141 | in _parallel_ because regions are ticking in _parallel_ (we CANNOT
142 | call them in a synchronous fashion, as this opens up deadlock issues
143 | and would handicap performance). There are no easy ways out of this,
144 | it depends solely on what data is being accessed. Sometimes a
145 | concurrent collection (like ConcurrentHashMap) is enough, and often a
146 | concurrent collection used carelessly will only _hide_ threading
147 | issues, which then become near impossible to debug.
148 |
149 | ### Current API additions
150 |
151 | To properly understand API additions, please read
152 | [Project overview](https://docs.papermc.io/folia/reference/overview).
153 |
154 | - RegionScheduler, AsyncScheduler, GlobalRegionScheduler, and EntityScheduler
155 | acting as a replacement for the BukkitScheduler.
156 | The entity scheduler is retrieved via Entity#getScheduler, and the
157 | rest of the schedulers can be retrieved from the Bukkit/Server classes.
158 | - Bukkit#isOwnedByCurrentRegion to test if the current ticking region
159 | owns positions/entities
160 |
161 | ### Thread contexts for API
162 |
163 | To properly understand API additions, please read
164 | [Project overview](https://docs.papermc.io/folia/reference/overview).
165 |
166 | General rules of thumb:
167 |
168 | 1. Commands for entities/players are called on the region which owns
169 | the entity/player. Console commands are executed on the global region.
170 |
171 | 2. Events involving a single entity (i.e player breaks/places block) are
172 | called on the region owning entity. Events involving actions on an entity
173 | (such as entity damage) are invoked on the region owning the target entity.
174 |
175 | 3. The async modifier for events is deprecated - all events
176 | fired from regions or the global region are considered _synchronous_,
177 | even though there is no main thread anymore.
178 |
179 | ### Current broken API
180 |
181 | - Most API that interacts with portals / respawning players / some
182 | player login API is broken.
183 | - ALL scoreboard API is considered broken (this is global state that
184 | I've not figured out how to properly implement yet)
185 | - World loading/unloading
186 | - Entity#teleport. This will NEVER UNDER ANY CIRCUMSTANCE come back,
187 | use teleportAsync
188 | - Could be more
189 |
190 | ### Planned API additions
191 |
192 | - Proper asynchronous events. This would allow the result of an event
193 | to be completed later, on a different thread context. This is required
194 | to implement some things like spawn position select, as asynchronous
195 | chunk loads are required when accessing chunk data out-of-region.
196 | - World loading/unloading
197 | - More to come here
198 |
199 | ### Planned API changes
200 |
201 | - Super aggressive thread checks across the board. This is absolutely
202 | required to prevent plugin devs from shipping code that may randomly
203 | break random parts of the server in entirely _undiagnosable_ manners.
204 | - More to come here
205 |
206 | ### Maven information
207 | * Maven Repo (for folia-api):
208 | ```xml
209 |