feat: add subinterpreters support

[XuehaiPan]

Description

Describe your changes in detail.

Motivation and Context

Why is this change required? What problem does it solve?
If it fixes an open issue, please link to the issue here.
You can use the syntax close #15213 if this solves the issue #15213

• I have raised an issue to propose this change (required for new features and bug fixes)

Resolves#103

Types of changes

What types of changes does your code introduce? Put an x in all the boxes that apply:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds core functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (update in the documentation)

Checklist

Go over all the following points, and put an x in all the boxes that apply.
If you are unsure about any of these, don't hesitate to ask. We are here to help!

• I have read the CONTRIBUTION guide. (required)
• My change requires a change to the documentation.
• I have updated the tests accordingly. (required for a bug fix or a new feature)
• I have updated the documentation accordingly.
• I have reformatted the code using make format. (required)
• I have checked the code using make lint. (required)
• I have ensured make test pass. (required)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (05691e7) to head (3b2bfa2).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@ Coverage Diff @@## main #245 +/- ##
=========================================
Coverage 100.00% 100.00% =========================================
Files 14 14 Lines 1416 1409 -7 Branches 175 174 -1 =========================================
- Hits 1416 1409 -7 

Flag	Coverage Δ
unittests	100.00% <ø> (ø)
unittests-cp310-Linux	100.00% <ø> (ø)
unittests-cp310-Windows	100.00% <ø> (ø)
unittests-cp310-macOS	100.00% <ø> (ø)
unittests-cp311-Linux	100.00% <ø> (ø)
unittests-cp311-Windows	100.00% <ø> (ø)
unittests-cp311-macOS	?
unittests-cp312-Linux	100.00% <ø> (ø)
unittests-cp312-Windows	?
unittests-cp312-macOS	100.00% <ø> (ø)
unittests-cp313-Linux	?
unittests-cp313-Windows	100.00% <ø> (ø)
unittests-cp313-macOS	100.00% <ø> (ø)
unittests-cp313t-Linux	?
unittests-cp313t-Windows	100.00% <ø> (ø)
unittests-cp313t-macOS	?
unittests-cp314-Linux	?
unittests-cp314-Windows	?
unittests-cp314-macOS	?
unittests-cp314t-Linux	?
unittests-cp314t-Windows	?
unittests-cp314t-macOS	?
unittests-cp39-Linux	100.00% <ø> (ø)
unittests-cp39-Windows	100.00% <ø> (ø)
unittests-cp39-macOS	?
unittests-pp311-Linux	100.00% <ø> (ø)
unittests-pp311-Windows	100.00% <ø> (ø)
unittests-pp311-macOS	100.00% <ø> (ø)
unittests-pydebug	?
unittests-pydebug-cp310d-Linux	?
unittests-pydebug-cp310d-Windows	?
unittests-pydebug-cp310d-macOS	?
unittests-pydebug-cp311d-Linux	?
unittests-pydebug-cp311d-Windows	?
unittests-pydebug-cp311d-macOS	?
unittests-pydebug-cp312d-Linux	?
unittests-pydebug-cp312d-Windows	?
unittests-pydebug-cp312d-macOS	?
unittests-pydebug-cp313d-Linux	?
unittests-pydebug-cp313d-Windows	?
unittests-pydebug-cp313d-macOS	?
unittests-pydebug-cp313td-Linux	?
unittests-pydebug-cp313td-Windows	?
unittests-pydebug-cp313td-macOS	?
unittests-pydebug-cp314d-Linux	?
unittests-pydebug-cp314d-Windows	?
unittests-pydebug-cp314d-macOS	?
unittests-pydebug-cp314td-Linux	?
unittests-pydebug-cp314td-Windows	?
unittests-pydebug-cp314td-macOS	?
unittests-pydebug-cp39d-Linux	?
unittests-pydebug-cp39d-Windows	?
unittests-pydebug-cp39d-macOS	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[XuehaiPan]

Code review

Found 1 issue:

1. Double-locking deadlock on sm_dict_order_mutex in FlattenInto and FlattenIntoWithPath. Both functions acquire a scoped_read_lock on PyTreeTypeRegistry::sm_dict_order_mutex, then call PyTreeTypeRegistry::IsDictInsertionOrdered() which unconditionally acquires the same lock internally. Since std::shared_mutex is not re-entrant (scoped_read_lock = std::shared_lock<std::shared_mutex>), this is undefined behavior per the C++ standard and will deadlock in practice. The fix is to remove the outer scoped_read_lock in flatten.cpp, since IsDictInsertionOrdered() already handles its own locking.

FlattenInto (outer lock):

optree/src/treespec/flatten.cpp

Lines 209 to 217 in 1ada0bb

	{
	#if defined(OPTREE_HAS_READ_WRITE_LOCK)
	const scoped_read_lock lock{PyTreeTypeRegistry::sm_dict_order_mutex};
	#endif
	is_dict_insertion_ordered = PyTreeTypeRegistry::IsDictInsertionOrdered(registry_namespace);
	is_dict_insertion_ordered_in_current_namespace =
	PyTreeTypeRegistry::IsDictInsertionOrdered(registry_namespace,
	/*inherit_global_namespace=*/false);
	}

FlattenIntoWithPath (same pattern):

optree/src/treespec/flatten.cpp

Lines 486 to 494 in 1ada0bb

	{
	#if defined(OPTREE_HAS_READ_WRITE_LOCK)
	const scoped_read_lock lock{PyTreeTypeRegistry::sm_dict_order_mutex};
	#endif
	is_dict_insertion_ordered = PyTreeTypeRegistry::IsDictInsertionOrdered(registry_namespace);
	is_dict_insertion_ordered_in_current_namespace =
	PyTreeTypeRegistry::IsDictInsertionOrdered(registry_namespace,
	/*inherit_global_namespace=*/false);
	}

IsDictInsertionOrdered (inner lock):

optree/include/optree/registry.h

Lines 164 to 174 in 1ada0bb

	// Check if should preserve the insertion order of the dictionary keys during flattening.
	[[nodiscard]]staticinline Py_ALWAYS_INLINE boolIsDictInsertionOrdered(
	const std::string &registry_namespace,
	constbool &inherit_global_namespace = true) {
	const scoped_read_lock lock{sm_dict_order_mutex};
	constauto interpid = GetCurrentPyInterpreterID();
	constauto &namespaces = sm_dict_insertion_ordered_namespaces;
	return (namespaces.find({interpid, registry_namespace}) != namespaces.end()) ||
	(inherit_global_namespace && namespaces.find({interpid, ""}) != namespaces.end());
	}

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}