Add test-api-v1 (feat: Scoped Events)

build.gradle

@@ -617,6 +617,7 @@ void setupRepositories(RepositoryHandler repositories) {
 def devOnlyModules = [
 	"fabric-client-gametest-api-v1",
 	"fabric-gametest-api-v1",
+	"fabric-dev-debug-api-v1"
 ]
 
 dependencies {

fabric-api-base/src/main/java/net/fabricmc/fabric/api/event/EventFactory.java

@@ -41,7 +41,7 @@ private EventFactory() { }
 	 * @return The Event instance.
 	 */
 	public static <T> Event<T> createArrayBacked(Class<? super T> type, Function<T[], T> invokerFactory) {
-		return EventFactoryImpl.createArrayBacked(type, invokerFactory);
+		return EventFactoryImpl.INSTANCE.createArrayBacked(type, invokerFactory);
 	}
 
 	/**

fabric-api-base/src/main/java/net/fabricmc/fabric/impl/base/event/ArrayBackedEvent.java

@@ -30,10 +30,10 @@
 import net.fabricmc.fabric.api.event.Event;
 import net.fabricmc.fabric.impl.base.toposort.NodeSorting;
 
-class ArrayBackedEvent<T> extends Event<T> {
+public class ArrayBackedEvent<T> extends Event<T> {
 	private final Function<T[], T> invokerFactory;
-	private final Object lock = new Object();
-	private T[] handlers;
+	protected final Object lock = new Object();
+	protected T[] handlers;
 	/**
 	 * Registered event phases.
 	 */
@@ -44,7 +44,7 @@ class ArrayBackedEvent<T> extends Event<T> {
 	private final List<EventPhaseData<T>> sortedPhases = new ArrayList<>();
 
 	@SuppressWarnings("unchecked")
-	ArrayBackedEvent(Class<? super T> type, Function<T[], T> invokerFactory) {
+	protected ArrayBackedEvent(Class<? super T> type, Function<T[], T> invokerFactory) {
 		this.invokerFactory = invokerFactory;
 		this.handlers = (T[]) Array.newInstance(type, 0);
 		update();
@@ -70,7 +70,7 @@ public void register(Identifier phaseIdentifier, T listener) {
 		}
 	}
 
-	private EventPhaseData<T> getOrCreatePhase(Identifier id, boolean sortIfCreate) {
+	protected final EventPhaseData<T> getOrCreatePhase(Identifier id, boolean sortIfCreate) {
 		EventPhaseData<T> phase = phases.get(id);
 
 		if (phase == null) {
@@ -86,7 +86,7 @@ private EventPhaseData<T> getOrCreatePhase(Identifier id, boolean sortIfCreate)
 		return phase;
 	}
 
-	private void rebuildInvoker(int newLength) {
+	protected final void rebuildInvoker(int newLength) {
 		// Rebuild handlers.
 		if (sortedPhases.size() == 1) {
 			// Special case with a single phase: use the array of the phase directly.

fabric-api-base/src/main/java/net/fabricmc/fabric/impl/base/event/EventFactoryImpl.java

@@ -24,6 +24,7 @@
 import java.lang.reflect.Modifier;
 import java.lang.reflect.Proxy;
 import java.util.Collections;
+import java.util.ServiceLoader;
 import java.util.Set;
 import java.util.function.Function;
 
@@ -33,18 +34,29 @@
 
 import net.fabricmc.fabric.api.event.Event;
 
-public final class EventFactoryImpl {
+public class EventFactoryImpl {
+	public static final EventFactoryImpl INSTANCE = ServiceLoader.load(EventFactoryImpl.class).findFirst().orElseGet(EventFactoryImpl::new);
 	private static final Set<ArrayBackedEvent<?>> ARRAY_BACKED_EVENTS
 			= Collections.newSetFromMap(new MapMaker().weakKeys().makeMap());
 
-	private EventFactoryImpl() { }
+	protected EventFactoryImpl() {
+		Class<?> thisClass = getClass();
+
+		if (thisClass != EventFactoryImpl.class && !thisClass.getName().equals("net.fabricmc.fabric.impl.debug.dev.TestableEventFactoryImpl")) {
+			throw new IllegalStateException("You are not allowed to create a custom EventFactoryImpl!");
+		}
+	}
 
 	public static void invalidate() {
 		ARRAY_BACKED_EVENTS.forEach(ArrayBackedEvent::update);
 	}
 
-	public static <T> Event<T> createArrayBacked(Class<? super T> type, Function<T[], T> invokerFactory) {
-		ArrayBackedEvent<T> event = new ArrayBackedEvent<>(type, invokerFactory);
+	protected <T> ArrayBackedEvent<T> doCreateArrayBacked(Class<? super T> type, Function<T[], T> invokerFactory) {
+		return new ArrayBackedEvent<>(type, invokerFactory);
+	}
+
+	public final <T> Event<T> createArrayBacked(Class<? super T> type, Function<T[], T> invokerFactory) {
+		ArrayBackedEvent<T> event = doCreateArrayBacked(type, invokerFactory);
 		ARRAY_BACKED_EVENTS.add(event);
 		return event;
 	}

fabric-api-base/src/main/java/net/fabricmc/fabric/impl/base/event/EventPhaseData.java

@@ -26,7 +26,7 @@
 /**
  * Data of an {@link ArrayBackedEvent} phase.
  */
-class EventPhaseData<T> extends SortableNode<EventPhaseData<T>> {
+public class EventPhaseData<T> extends SortableNode<EventPhaseData<T>> {
 	final Identifier id;
 	T[] listeners;
 
@@ -42,6 +42,25 @@ void addListener(T listener) {
 		listeners[oldLength] = listener;
 	}
 
+	public boolean removeListener(T listener) {
+		int indexToRemove;
+
+		for (indexToRemove = listeners.length - 1; indexToRemove >= 0; indexToRemove--) {
+			if (listeners[indexToRemove] == listener) {
+				break;
+			}
+		}
+
+		if (indexToRemove == -1) {
+			return false;
+		}
+
+		T[] newListeners = Arrays.copyOf(listeners, listeners.length - 1);
+		System.arraycopy(listeners, indexToRemove + 1, newListeners, indexToRemove, newListeners.length - indexToRemove);
+		listeners = newListeners;
+		return true;
+	}
+
 	@Override
 	protected String getDescription() {
 		return id.toString();

fabric-debug-api-v1/src/main/resources/fabric.mod.json

@@ -17,10 +17,9 @@
   ],
   "depends": {
     "fabricloader": ">=0.18.4",
-    "fabric-api-base": "*",
-    "fabric-registry-sync-v0": "*"
+    "fabric-api-base": "*"
   },
-  "description": "A toolkit for registering and using debug subscriptions and other debug tools Mojang have created.",
+  "description": "A toolkit for using debug tools Mojang have created and other utilities in tests and development.",
   "mixins": [
     "fabric-debug-api-v1.mixins.json",
     {

fabric-dev-debug-api-v1/build.gradle

@@ -0,0 +1,10 @@
+version = getSubprojectVersion(project)
+
+moduleDependencies(project, [
+	'fabric-api-base',
+	'fabric-debug-api-v1'
+])
+
+testDependencies(project, [
+	'fabric-gametest-api-v1'
+])

fabric-dev-debug-api-v1/src/main/java/net/fabricmc/fabric/api/debug/dev/v1/EventScope.java

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.api.debug.dev.v1;
+
+import java.util.function.Function;
+
+import org.jetbrains.annotations.ApiStatus;
+
+import net.minecraft.resources.Identifier;
+
+import net.fabricmc.fabric.api.event.Event;
+import net.fabricmc.fabric.api.event.EventFactory;
+import net.fabricmc.fabric.impl.debug.dev.EventScopeImpl;
+
+/**
+ * Represents a wrapper around a short-lived {@link Event}.
+ * This class implements {@link AutoCloseable} and is intended to be used in a try-with-resources block.
+ * When closed, the event will be unregistered.
+ */
+@ApiStatus.NonExtendable
+public interface EventScope extends AutoCloseable {
+	@Override
+	void close();
+
+	/**
+	 * @param event The {@link Event} to be registered in an {@link EventScope}
+	 * @param listener The event listener
+	 * @param <T> is the type parameter for the event's listener
+	 * @return a new {@link EventScope} instance holding the event, its listener and the event phase {@link Event#DEFAULT_PHASE}
+	 */
+	static <T> EventScope registerScoped(Event<T> event, T listener) {
+		return registerScoped(event, Event.DEFAULT_PHASE, listener);
+	}
+
+	/**
+	 * @param event The {@link Event} to be registered in an {@link EventScope}
+	 * @param phase The {@linkplain EventFactory#createWithPhases(Class, Function, Identifier...) event phase}
+	 * @param listener The event listener
+	 * @param <T> is the type parameter for the event's listener
+	 * @return a new {@link EventScope} instance holding the event, its listener and the event phase
+	 * @see EventFactory#createWithPhases(Class, Function, Identifier...)
+	 */
+	static <T> EventScope registerScoped(Event<T> event, Identifier phase, T listener) {
+		return EventScopeImpl.registerScoped(event, phase, listener);
+	}
+}

fabric-dev-debug-api-v1/src/main/java/net/fabricmc/fabric/impl/debug/dev/EventScopeImpl.java

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.impl.debug.dev;
+
+import net.minecraft.resources.Identifier;
+
+import net.fabricmc.fabric.api.debug.dev.v1.EventScope;
+import net.fabricmc.fabric.api.event.Event;
+
+public class EventScopeImpl<T> implements EventScope {
+	private final TestableArrayBackedEvent<T> event;
+	private final Identifier phase;
+	private final T listener;
+
+	public EventScopeImpl(TestableArrayBackedEvent<T> event, Identifier phase, T listener) {
+		this.event = event;
+		this.phase = phase;
+		this.listener = listener;
+	}
+
+	public static <T> EventScope registerScoped(Event<T> event, Identifier phase, T listener) {
+		if (!(event instanceof TestableArrayBackedEvent<T> testableEvent)) {
+			throw new IllegalArgumentException("Event is not testable, something has gone very wrong!");
+		}
+
+		event.register(phase, listener);
+		return new EventScopeImpl<>(testableEvent, phase, listener);
+	}
+
+	@Override
+	public void close() {
+		event.unregister(phase, listener);
+	}
+}

fabric-dev-debug-api-v1/src/main/java/net/fabricmc/fabric/impl/debug/dev/TestableArrayBackedEvent.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.impl.debug.dev;
+
+import java.util.Objects;
+import java.util.function.Function;
+
+import net.minecraft.resources.Identifier;
+
+import net.fabricmc.fabric.impl.base.event.ArrayBackedEvent;
+
+public class TestableArrayBackedEvent<T> extends ArrayBackedEvent<T> {
+	TestableArrayBackedEvent(Class<? super T> type, Function<T[], T> invokerFactory) {
+		super(type, invokerFactory);
+	}
+
+	public void unregister(Identifier phaseIdentifier, T listener) {
+		Objects.requireNonNull(phaseIdentifier, "Tried to unregister a listener for a null phase!");
+		Objects.requireNonNull(listener, "Tried to unregister a null listener!");
+
+		synchronized (lock) {
+			if (getOrCreatePhase(phaseIdentifier, false).removeListener(listener)) {
+				rebuildInvoker(handlers.length - 1);
+			}
+		}
+	}
+}

fabric-dev-debug-api-v1/src/main/java/net/fabricmc/fabric/impl/debug/dev/TestableEventFactoryImpl.java

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2016, 2017, 2018, 2019 FabricMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package net.fabricmc.fabric.impl.debug.dev;
+
+import java.util.function.Function;
+
+import net.fabricmc.fabric.impl.base.event.ArrayBackedEvent;
+import net.fabricmc.fabric.impl.base.event.EventFactoryImpl;
+
+public class TestableEventFactoryImpl extends EventFactoryImpl {
+	@Override
+	protected <T> ArrayBackedEvent<T> doCreateArrayBacked(Class<? super T> type, Function<T[], T> invokerFactory) {
+		return new TestableArrayBackedEvent<>(type, invokerFactory);
+	}
+}

fabric-dev-debug-api-v1/src/main/resources/META-INF/services/net.fabricmc.fabric.impl.base.event.EventFactoryImpl

@@ -0,0 +1 @@
+net.fabricmc.fabric.impl.debug.dev.TestableEventFactoryImpl

fabric-dev-debug-api-v1/src/main/resources/fabric.mod.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "id": "fabric-dev-debug-api-v1",
+  "name": "Fabric Dev Debug API (v1)",
+  "version": "${version}",
+  "environment": "*",
+  "license": "Apache-2.0",
+  "icon": "assets/fabric-dev-debug-api-v1/icon.png",
+  "authors": [
+    "FabricMC"
+  ],
+  "depends": {
+    "fabricloader": ">=0.18.4",
+    "fabric-api-base": "*",
+    "fabric-debug-api-v1": "*"
+  },
+  "description": "An extension of Debug API with features only available in development environments.",
+  "custom": {
+    "fabric-api:module-lifecycle": "experimental"
+  }
+}