Documentation should mention that it is unnecessary to release returned objects
bytesized opened this issue · 2 comments
Coming from C++
COM, where very simple COM usage looks like
IFoo* foo;
HRESULT hr = CoCreateInstance(rclsid, pUnkOuter, dwClsContext, riid, (void**) &foo);
if (SUCCEEDED(hr)) {
// do something with foo...
foo->Release()
}
it was highly confusing to try out this library for the first time and do something like this
>>> try:
... foo = CreateObject(progid)
... except:
... pass
... else:
... # Do something with foo
... foo.Release()
...
0
>>> foo = None
Exception ignored in: <function _compointer_base.__del__ at 0x0000020D7D3FC3A0>
Traceback (most recent call last):
File "C:\Users\bytesized\sandbox\python\venv\lib\site-packages\comtypes\_post_coinit\unknwn.py", line 386, in __del__
self.Release()
File "C:\Users\bytesized\sandbox\python\venv\lib\site-packages\comtypes\_post_coinit\unknwn.py", line 534, in Release
return self.__com_Release() # type: ignore
OSError: exception: access violation writing 0x0000000000000000
I tried looking through the documentation for CreateObject
and using the search bar to look for "Release" and a few similar search terms, but couldn't find anything related.
This feels weird since AddRef
and Release
are standard COM methods and are made available to the interface consumer. They just don't quite seem to work as expected. Normally, things are handed to you (by CoCreateInstance
, for example) already AddRef
ed. So you have to Release
them, plus an additional Release
for every additional AddRef
. But this implementation does not match this; it's strictly one Release
per AddRef
.
It seems like if this COM library is going to differ from the usual COM conventions, the documentation should at least mention it.
Hi, @bytesized.
Indeed, those who are familiar with COM and are used to explicitly releasing COM interface pointers that are no longer in use might find this package's implementation weird.
The originator of this package likely aimed to make it easier for users to work with the COM framework by using atexit
and __del__
to trigger cleanup operations, so that users would not need to manually release COM pointers that are no longer in use.
Through the functionality of metaclasses, when an instance of an IUnknown
Python object is destroyed and __del__
is called, Release
is automatically triggered.
comtypes/comtypes/_post_coinit/unknwn.py
Lines 371 to 386 in 3e3977d
Additionally, it's worth mentioning that when the _shutdown
callback function registered with atexit
is invoked, comtypes
not only calls the Release
method on each COM interface pointer but also calls CoUninitialize
.
Line 180 in 3e3977d
comtypes/comtypes/_post_coinit/unknwn.py
Lines 25 to 47 in 3e3977d
comtypes/comtypes/_post_coinit/unknwn.py
Lines 54 to 66 in 3e3977d
It is true that there is no documentation indicating that users generally do not need to manually call Release
, CoInitialize
at startup, or CoUninitialize
at shutdown.
We welcome PRs to add explanations about these behaviors, so please feel free to contribute.
In the past, changes were made in #215 to define _shutdown
as a private function, allowing cleanup operations to be unregister
ed from atexit
.
By temporarily modifying IUnknown._com_shutting_down
manually, it is also possible to prevent Release
from being called when __del__
is invoked.
However, I should mention that if alternative cleanup operations are not performed or the modified class attributes are not restored, it will be necessary to manually and properly release the COM pointers present in the running Python interpreter.