`corrupted double-linked list

[YeziLover]

Under multiprocessing (fork) mode, importing and using from cv2.xfeatures2d import matchGMS in the official OpenCV build occasionally triggers a corrupted double-linked list error. Is there a reliable fix?

[BhumikaTechHub]

From the description, this looks like a native heap corruption issue triggered when using OpenCV (specifically xfeatures2d.matchGMS) under multiprocessing with fork start method. Since this repository only handles Python wheel packaging and not the OpenCV C++ implementation itself, the root cause is likely upstream in opencv/opencv or opencv/opencv_contrib, rather than in the packaging scripts here.

As a workaround, users may want to:

Switch multiprocessing start method to spawn

import multiprocessing as mp  
mp.set_start_method("spawn", force=True)

Import cv2 inside the worker process instead of at module import time

Try limiting OpenMP threads (e.g. OMP_NUM_THREADS=1)

It might also be helpful to track this issue in the core OpenCV repository if not already done, since it appears to be related to native memory management rather than wheel building.

[molhamfetnah]

I've worked on memory corruption issues in OpenCV (PRs #28936, #28913).

Technical Analysis:
"corrupted double-linked list" typically indicates heap corruption, often caused by:

1. Double-free of memory
2. Buffer overflow corrupting heap metadata
3. Use-after-free in OpenCV's internal data structures

Root Cause (likely):

• Memory allocated by OpenCV being freed by Python garbage collector
• Race condition in reference counting
• Incompatible memory allocators between Python and OpenCV

Fix Strategy:

1. Review reference counting in Python bindings
2. Ensure proper lifetime management for Mat objects
3. Add defensive checks

This is a complex memory issue. Happy to help investigate.

[molhamfetnah]

I've submitted a PR with documentation about this issue:

PR: #1225

Summary:
This is a known limitation of OpenCV - the C++ core would need handlers to properly reset internal state on fork. The PR adds documentation to the cv2 module explaining the issue and workarounds.

Workarounds (use one):

1. Use spawn mode:
2. Disable OpenCV threads: in each worker before using cv2

This is the same root cause as issue #5150 in the main OpenCV repo.