Threadcore API

Threadcore API

This is the half of Threadcore that other mods compile against. If you just want the mod, go and
install Threadcore instead, it depends on
this and will tell you to come and get it.

With Threadcore installed, part of the server tick runs on region worker threads instead of the main
thread. Most mods never have to care about that, because Threadcore guards the dangerous paths and
defers anything crossing a region back to the main thread. This is for when you want the other
thing: your own mod doing its work out there in parallel, on purpose, instead of being guarded on
the way past.

What you can do with it

RegionScheduler runs a task on the thread that owns a given block, chunk or region, so your work
happens alongside the rest of the world rather than queueing up behind it.

MutationGate lets you change a block, or run any other mutation, from a region thread. It gets
deferred and replayed on the main thread in order, so you do not have to write your own queue to
stay correct.

SnapshotService reads block state off thread from a frozen copy of that tick, so you are not
racing the world while you read it.

ThreadGuard, ThreadContext and ThreadDomain tell you what kind of thread you are on and let
you assert that you are where you think you are. In strict mode you hear about a violation when it
happens, instead of finding a corrupted world three hours later.

@RegionSafe, @AsyncReadOnly and @RequiresMainEquivalent let you write your threading contract
down on the method, and ContractValidator checks it for you.

It is safe to depend on when Threadcore is not installed

Every accessor returns null until Threadcore installs its implementations, and isAvailable() tells
you whether it has. So you can soft depend on this, take the fast path when Threadcore is there,
fall back to ordinary main thread behaviour when it is not, and ship one jar either way.

if (ThreadcoreAPI.isAvailable()) {
    ThreadcoreAPI.getScheduler().scheduleAt(worldKey, pos, () -> { /* on the owning region */ });
} else {
    runOnMainThreadAsUsual();
}

Which Minecraft versions, which is really a question about Java

There is no Minecraft code in this jar and it declares no Minecraft dependency, so Minecraft does
not constrain it. What it needs is Java 16 or newer.

That means 1.17 and up works with no upper bound, because every release from 1.17 on ships Java 16,
17, 21 or 25, so this will keep working on versions that do not exist yet. On 1.16.5 and below it
only works if your server is running Java 16 or newer. Those versions ship Java 8 by default, and
while it loads fine on a newer JVM, that is your call to make rather than a promise from me.

Java 16 is the floor because BlockVec, ChunkVec, RegionKey and TickStats are records.
Building for Java 11 or 8 gives 62 “records are not supported” errors, so getting down there would
mean gutting the public API to reach servers that could just run a newer JVM instead.

Using it

repositories {
    maven { url = 'https://maven.pkg.github.com/mrimmortal1749/shadowmark-threadcore' }
}
dependencies {
    modImplementation 'net.threadcore:threadcore-api:0.1.0'
}

Then declare it in your own fabric.mod.json, as a hard dependency if your mod needs it:

"depends":  { "threadcore-api": ">=0.0.2" }

or as a suggestion if your mod works with or without it:

"suggests": { "threadcore-api": ">=0.0.2" }

Depend on it, do not bundle it inside your own jar. Fabric keeps the highest version of a shared
library and breaks ties between equal ones arbitrarily, so a bundled older copy can win the tie even
on a server that has the current one installed. That is not hypothetical, it is what caused a
NoSuchMethodError at boot once already, and Threadcore now stops at startup and names the mod that
is doing it.

Licence

Apache-2.0, so use it, modify it, ship it inside a closed source mod. That is what it is there for.
The grant covers this API module only. Threadcore itself is All Rights Reserved and is a separate
project, and the licence does not give you any rights to the Threadcore name or logo.

Status

This is a beta. The surface is small on purpose. Everything in it is something Threadcore already
does, so there is nothing in here that has not had to work first.