Document dlclose restrictions for Go-based (cgo) drivers
- Dominant language
- C#
- Stars
- 627
- Forks
- 217
- Avg merge
- 17h
- Merged PRs (30d)
- 57
Description
### What feature or improvement would you like to see?
Following up on the discussion in https://github.com/apache/arrow-adbc/discussions/4206#discussioncomment-16550014
- **Go-based drivers** (Flight SQL, Snowflake): `dlclose` hangs or crashes because the Go runtime does not support clean unload (golang/go#11100). The Rust driver manager already works around this by skipping `dlclose` (#3844, https://github.com/apache/arrow-adbc/pull/3291), but this is not documented in the C API.
- **C/C++ drivers** (SQLite, PostgreSQL): presumably safe, but not documented either.
- **Rust drivers**: untested per maintainer.
Embedders integrating the C driver manager (e.g., StarRocks, DuckDB) currently have to discover this through the Rust manager's changelog or by debugging hangs at process shutdown.
**Proposal**: add a section to the C driver manager (maybe for JNI part as well) documentation covering:
1. `dlclose` must not be called on Go-based driver handles. Driver handles should stay resident until process exit.
2. Cleanup should go through the ADBC API only: `AdbcStatementRelease` -> `AdbcConnectionRelease` -> `AdbcDatabaseRelease`.
3. Multiple Go-based drivers can be `dlopen`-ed in the same process on Linux and ARM macOS, but not on Intel macOS (due to an unresolved Go runtime bug).
Contributor guide
Research direction
Start with the C driver manager documentation and the linked discussion in issue #4210. Check how the Rust driver manager handles dlclose and confirm the documented Go, C/C++, and Rust behavior before adding guidance for the ADBC cleanup sequence and platform limitations. Done means embedders can find these restrictions in the C API documentation.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c, go
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100