Make MuJoCo Python bindings compatible with free-threading.

Introduce a new header `gil.h` defining `MutexLockIfGilDisabled` to support thread-safety in both standard and free-threaded CPython builds.

Protect critical shared states and registries:
- Guard global Python callback pointers in `callbacks.cc` using a mutex. Move `gil_scoped_acquire` into local blocks around refcount modifications to prevent `longjmp` from bypassing destructors.
- Protect raw pointer maps in `structs_wrappers.cc` with static mutexes.
- Replace TOCTOU race in `mjcb_time` initialization with thread-safe `std::call_once`.
- Add synchronization to lazy indexer array cache initialization in `indexers.cc` and `indexer_xmacro.h`.
- Protect vector mutations in `StructListBase::PopulateUpTo` in `structs.h` with a mutex.
- Revert unnecessary atomic changes to threadpool counters.
- Declare free-threading compatibility by passing `pybind11::mod_gil_not_used()` to all extension modules.

Fixes #3259
Fixes #3256
Fixes #2978

PiperOrigin-RevId: 941101502
Change-Id: Iec4ce58afcbc75d4b0be6a9a21fc8a47854242e3

python/mujoco/gil.h

@@ -0,0 +1,62 @@
+// Copyright 2026 DeepMind Technologies Limited
+//
+// 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.
+
+#ifndef MUJOCO_PYTHON_GIL_H_
+#define MUJOCO_PYTHON_GIL_H_
+
+#include <mutex>
+
+namespace mujoco::python {
+
+// A scoped lock that acquires a std::mutex in free-threaded Python builds
+// (Py_GIL_DISABLED) and does nothing in standard GIL builds.
+//
+// In standard builds the GIL already serializes access to Python state, so
+// adding a C++ mutex would introduce unnecessary overhead and deadlock risk
+// (two locks held simultaneously). In free-threaded builds the GIL is absent,
+// so an explicit mutex is required to protect shared mutable C++ state.
+//
+// Usage:
+//   static std::mutex my_mutex;
+//   {
+//     MutexLockIfGilDisabled lock(my_mutex);
+//     // ... access shared state ...
+//   }
+#ifdef Py_GIL_DISABLED
+class MutexLockIfGilDisabled {
+ public:
+  explicit MutexLockIfGilDisabled(std::mutex& mtx) : lock_(mtx) {}
+  MutexLockIfGilDisabled(const MutexLockIfGilDisabled&) = delete;
+  MutexLockIfGilDisabled& operator=(const MutexLockIfGilDisabled&) = delete;
+
+ private:
+  std::lock_guard<std::mutex> lock_;
+};
+#else
+class MutexLockIfGilDisabled {
+ public:
+  explicit MutexLockIfGilDisabled(std::mutex& /*unused*/) {}
+  MutexLockIfGilDisabled(const MutexLockIfGilDisabled&) = delete;
+  MutexLockIfGilDisabled& operator=(const MutexLockIfGilDisabled&) = delete;
+};
+#endif
+
+inline std::mutex& GetCallbackMutex() {
+  static std::mutex mtx;
+  return mtx;
+}
+
+}  // namespace mujoco::python
+
+#endif  // MUJOCO_PYTHON_GIL_H_