We use Native COM support in our code havily. Everything's fine except that we don't like the fact that on error _com_raise_error() is called which throws a _com_error exception. Since we have our own hierarchy of exceptions catching this _com_error is inconvenient - it's not in our hierarchy and even doesn't inherit from std::exception.
So we need to override the _com_raise_error(). It's easy by itself - just define it in our code, the linker will link with it.
However is unclear who owns the IErrorInfo. The signature is
void __stdcall _com_raise_error( HRESULT hr, IErrorInfo* info );
So whoever calls the function would be responsible for calling IErrorInfo::Release() after the function returns. But how would the function return at all if we throw an exception in it and the control would transfer somewhere else?
I checked - called AddRef(), then Release() immediately upon entry into that function - the reference counter is 1. Later we pass ownership to the constructed exception object - it calls AddRef() in its constructor and Release() in destructor. I suppose this is incorrect since the AddRef() will increase the reference count to 2 but then only one Release() will be called (in the exception destructor).
Am I correct that the AddRef() in the constructor will cause a memory leak or is there some internal mechanism that doesn't allow IErrorInfo objects to leak at all?
_com_raise_error() is not meant to return. It must raise an exception, regardless of its type. If you look at the default implementation of _com_raise_error(), the raised _com_error object takes ownership of the specified IErrorInfo object. _com_error's constructor has an fAddRef parameter that has a default value of false, so AddRef() is not called. Release() is then called when the _com_error object is destructed by whatever exception handler catches it, thus freeing the IErrorInfo object.
I would imagine that _com_raise_error will call SetErrorInfo, passing it your IErrorInfo object. The contract for that is that the reference to the info is stored in a thread local, so whenever you set a new info, old one is released. Furthermore, whenever someone calls GetErrorInfo afterwards, ownership of info is transferred to that caller. So it's caller's obligation to call GetErrorInfo after every failed call that may set it, and release the object accordingly.
Thus, SetErrorInfo (as any other conventional COM call) will call AddRef on your object, so you do must not initialize it with a counter of 1.
Adding to the other answers, here are a couple of thoughts:
The general COM rule is that in-parameters do not need to be AddRef:ed at any level, since calls are synchronous and the reference count can't magically change while the method runs.
Every AddRef call represents a new stable reference to the object, that is, after calling AddRef, you can count on the object still being there. That means, if you want to store an interface pointer for later perusal, you should call AddRef. When you no longer care about the object's survival, call Release.
So, since you want to throw an exception object containing an IErrorInfo pointer, that object should AddRef it, since it needs the pointed-to-object to survive. Its destructor would typically Release.
I don't think SetErrorInfo needs to be involved in this -- it's the C alternative to throwing an exception.
Related
I am writing code that utilizes COM interfaces. I am basing my code on examples that I have found online. I do not want to utilize smart pointers in this case because I want to understand the basics of COM and not just have a smart pointer class do all of the work for me.
In order to frame my questions, let's assume I have a class similar to the following:
public class TestClass
{
private:
IUnknown *m_pUnknown;
public:
TestClass();
void AssignValue();
}
TestClass::TestClass()
{
m_pUnknown = NULL;
}
void TestClass::AssignValue()
{
IUnknown *pUnknown = NULL;
//Assign value to pUnknown here - not relevant to my questions
m_pUnknown = pUnknown;
pUnknown->Release();
}
Now on to my specific questions.
1) The examples I've seen to not use AddRef() when initializing a value, such as in the class constructor. Does the AddRef() happen "automatically" behind the scenes when a COM pointer is first assigned a value?
2) Although my code example does not show it, it is my understanding that in the AssignValue() method, when you assign a second value to overwrite the value of pUnknown (originally set in the class constructor), Release() is automatically called. After assigning the new value to pUnknown its reference count stands at zero. I need to call pUnknown->AddRef() immediately after the reassignment. Is my understanding correct?
Notes: I assume we are ignoring exceptions for simplicity here. If this was for real, you would want to use smart pointers to help keep things straight in the presence of exceptions. Similarly, I am not worrying about proper copying or destruction of instances of your example class or multi-threading. (Your raw pointers cannot be used from different threads as simply as you might assume.)
First, You need to make any necessary calls to COM. The only way anything might happen "automatically" behind the scenes would be if you were using smart pointers to do them.
1) The examples you refer to have to be getting their COM interface pointers from somewhere. This would be by making COM calls, e.g., CoCreateInstance() and QueryInterface(). These calls are passed the address of your raw pointer and set that raw pointer to the appropriate value. If they weren't also implicitly AddRef'ed, the reference count might be 0 and COM could delete the associated COM object before your program could do anything about it. So such COM calls must include an implicit AddRef() on your behalf. You are responsible for a Release() to match this implicit AddRef() that you instigated with one of these other calls.
2a) Raw pointers are raw pointers. Their value is garbage until you arrange for them to be set to something valid. In particular, assigning a value to one will NOT auto-magically call a function. Assigning to a raw pointer to an interface does not call Release() - you need to do that at the appropriate time. In your post, it appears that you are "overwriting" a raw pointer that had previously been set to NULL, hence there was no existing COM interface instance in the picture. There could not have been an AddRef() on something that doesn't exist, and must not be a Release() on something that isn't there.
2b)
Some of the code you indicated by a comment in your example is very relevant, but can easily be inferred. You have a local raw pointer variable, pUnknown. In the absent code, you presumably use a COM call that obtains an interface pointer, implicitly AddRefs it, and fills in your raw pointer with the proper value to use it. This gives you the responsibility for one corresponding Release() when you are done with it.
Next, you set a member raw pointer variable (m_pUnknown) with this same value. Depending on the previous use of this member variable, you might have needed to call Release() with its former value before doing this.
You now have 2 raw pointers set to the value to work with this COM interface instance and responsibility for one Release() due to 1 implicit AddRef() call. There are two ways to deal with this, but neither is quite what you have in your sample.
The first, most straightforward, and proper approach (which others have correctly pointed out & I skipped passed in the first version of this answer) is one AddRef() and one Release() per pointer. Your code is missing this for m_pUnknown. This requires adding m_pUnknown->AddRef() immediately after the assignment to m_pUnknown and 1 corresponding call to Release() "someplace else" when you are done using the current interface pointer from m_pUnknown. One usual candidate for this "someplace else" in your code is in the class destructor.
The second approach is more efficient, but less obvious. Even if you decide not to use it, you may see it, so should at least be aware of it. Following the first approach you would have the code sequence:
m_pUnknown = pUnknown;
m_pUnknown->AddRef();
pUnknown->Release();
Since pUnknown and m_pUnknown are set the same here, the Release() is immediately undoing the AddRef(). In this circumstance, eliding this AddRef/Release pair is reference count neutral and saves 2 round trips into COM. My mental model for this is a transfer of the interface and reference count from one pointer to the other. (With smart pointers it would look like newPtr.Attach( oldPtr.Detach() ); ) This approach leaves you with the original/not shown implicit AddRef() and needing to add the same m_pUnknown->Release() "someplace else" as in the first alternative.
In either approach, you exactly match AddRefs (implicit or explicit) with Releases for each interface and never go to a 0 reference count until you are done with the interface. Once you do hit 0, you do not attempt to use the value in the pointer.
Avi Berger already posted a great answer, but here is the same thing stated another way in case it helps with understanding.
In COM, reference counting is done within the COM object. The COM runtime will destruct and free an object whose reference count reaches 0. (This might be delayed by some time from the point of the count hitting 0).
Everything else is a convention. The usual convention amongst C++ COM programmers is that raw interface pointers should be treated as owning pointers. This concept means that any time a pointer points to a COM object, the pointer owns that object.
Using this terminology, the object may have multiple owners at any one time, and the object will be destroyed when nobody owns it.
However, raw pointers in C++ don't have ownership semantics built in. So you have to implement it yourself by making function calls:
Call AddRef on an interface pointer when that pointer takes ownership of an object. (You'll need to be aware of which Windows API functions or other library functions already do this, to avoid you doing it twice)
Call Release on an interface pointer when that pointer is about to stop owning an object.
The benefit of smart pointers is that they make it impossible for you to forget to call Release when an interface pointer stops owning an object. This includes the following cases:
Pointer goes out of scope.
Pointer is made to stop pointing to the object, by using assignment operator.
So, looking at your sample code. You have the pointer m_pUnknown. You want this pointer to take ownership of the object, so the code should be:
m_pUnknown = pUnknown;
m_pUnknown->AddRef();
You will also need to add code to your class destructor and your class assignment operator to call m_pUnknown->Release(). I would very strongly recommend wrapping these calls in the smallest class possible (that is, write your own smart pointer and make TestClass have that smart pointer as a member variable). Assuming of course you don't want to use an existing COM smart pointer class for pedagogical reasons.
The call pUnknown->Release(); is correct because pUnknown currently owns the object, and the pointer is about to stop owning the object due to the fact that it will be destroyed when the function block ends.
You may observe that it would be possible to remove both of the lines m_pUnknown->AddRef() and pUnknown->Release(). The code will behave exactly the same. However , it is better to follow the convention outlined above. Sticking to a convention helps yourself to avoid errors and it also helps other coders to understand your code.
To put it another way, the usual convention is to think of the pointer as having a reference count of either 0 or 1, even though the reference counting is not actually implemented that way.
First, my apologies. My attempt to simplify my code for the sake of clarity turned out to be misguided. However, I believe my questions were answered. If I may, I will summarize.
1) Any COM object that is assigned a value other than NULL needs to be immediately followed by AddRef() unless the AddRef() was implicitly handled (as is the case with some Windows API calls).
2) Any reassignment of value to a COM pointer, assuming that the "before" value is not NULL must be immediately proceeded by Release(). AddRef() would then by needed as mentioned in #1.
3) Any COM variable whose value needs to be preserved beyond its current scope requires that it have a reference count of at least 1 upon exiting its said scope. This may mean that an AddRef() is required.
Would this be a fair summary? Did I miss anything?
1)What is the exact difference of the following two ways of creating an object from a class named "handler"
handler myhandler;
handler myhandler=new handler();
2) Is the following alwasy possible?
handler *myhandler;
handler *myhandler=new handler();
handler myhandler;
That creates an object. If it's inside a function, then it has automatic storage duration, and will be destroyed automatically when it goes out of scope. If it's outside a function, then it has static storage duration, and will be destroyed automatically at the end of the program.
handler myhandler=new handler();
That probably doesn't compile; unless handler has a strange constructor allowing implicit conversion from a pointer, in which case it does something strange.
handler *myhandler;
That declares a pointer, which could be used to refer to an object of type handler. It doesn't create an object, nor does it point to any object yet.
handler *myhandler=new handler();
That creates a dynamic object, and initialises a pointer to point to it. This is usually a bad idea, since it's likely to lead to a memory leak (or worse) when you fail to delete it correctly. Don't create dynamic objects unless you really need them to outlive the current scope; and use a smart pointer when you do need to:
auto myhandler = std::make_unique<handler>(); // C++14
std::unique_ptr<handler> myhandler(new handler); // C++11
If you really want to juggle a raw pointer for educational purposes, then remember to delete the object once you've finished with it:
delete myhandler;
and take special care to make sure this only happens once, and happens even if an exception is thrown.
Short answer is that the second method is correct. The first creates a new object and then assigns a new object on top of it. I strongly recommend understanding this before proceeding:
http://www.parashift.com/c++-faq/self-assignment-how.html
Your program should not compile as you are redefining an object in both the case.
Your first case should not compile at new statement as new returns a pointer to the newly created object unless there is a constructor taking pointer or assignment operator overloaded which takes handler pointer.
In the second case, it will point to newly created object.
To correct first case,
handler myhandler=handler();
provided handler has a default constructor or constructor with default arguments.
I was wondering if it is standard practice in COM libraries to call Addref on an COM interface, that is returned from a function. For instance:
IXMLDOMElement* domElement = NULL;
document_->get_documentElement(&domElement); // does get_documentElement() call Addref on domElement?
// ...
// do something with domElement
// ..
domElement.Release(); // correct?
// (btw. member variable document_ is of type CComPtr<IXMLDOMDocument2>
or with a smart pointer:
CComPtr<IXMLDOMElement> domElement;
document_->get_documentElement(&domElement);
Btw. I found that in the docs of MSXML for "Windows media 9 series" it says that Addref is called: http://msdn.microsoft.com/en-us/library/ms751196(v=vs.85).aspx
But in the official documentation nothing is mentioned about it:
http://msdn.microsoft.com/en-us/library/ms759095(v=vs.85).aspx
The function that returns an interface pointer must call AddRef() on it before exiting, not the function that is receiving the object. The function that receives the interface pointer must use it as-is and then call Release() on it. Which means that get_documentElement() will call AddRef(), so do not call it yourself.
The rules for who - the caller or the callee - is responsible for doing what in regards to reference counting and memory management in COM are clearly defined in COM's documentation on MSDN:
The Rules of the Component Object Model
Reference Counting Rules
Yes you are supposed to addref before returning a COM object, as the caller is going to have an new interface pointer referencing the object, so the reference count needs to be increased by one. This is the rule, not the exception.
Documenting the internal addref is the exception, however, as reference counting is one of the fundamentals of COM. Probably the documentation was written when a lot of callers of this method don't know the rule and caused too many memory leaks.
When you, as a caller, no longer need the received object, you need to call Release directly or indirectly (e.g. through a class destructor), and stop using the reference pointer (many people set the pointer to null to prevent dangling pointers).
I came across a leak in a Direct3D application of mine, and I ended up correcting it, but I think the cause of the leak was due to my misunderstanding of how Direct3D handles its memory and interfaces.
I haven't been able to find a definitive article/tutorial on it (please provide one if you have one), but from what I've gathered, it works as such:
Every time you call a Get method, the number of references for the object returned is incremented. So if I call GetRenderTarget, the surface being rendered to has its reference count incremented.
Calling Release on the interface decrements its reference count. These first two points combined essentially mean: every time you get an interface, release it after you're done with it.
When the reference count reaches 0, the instance is deleted.
I'm not entirely sure if this is correct, but it seems to work in practice. If someone could clarify/confirm how it works, that'd be great.
P.S, are there any safeguards implemented in releasing interfaces? Calling Release any number of times on the back buffer doesn't seem to do any damage (which is a good thing, but I'm not sure why it doesn't).
Direct3D is based on COM, which is a technology that's at least 15 years old. Seems many people claim COM is dead and for that reason many overlook it, but reality is that there are many things in windows including Direct3D and MS's new Media Foundation that are all based on COM.
I strongly suggest you take a look at general COM programming. There are plenty of books and resources, but many of them are rather old but that's ok because the root of the technology hasn't changed for a very long time.
Basically what you've observed is interface reference counting. COM is based purely on accessing objects via interfaces, which all derive from the base interface, IUnknown. IUnknown implements methods AddRef() and Release() and it is the responsibility of your application to call AddRef() whenever you store a local copy of a pointer and to call Release() whenever that local copy is no longer needed.
When you have methods with interface out parameters (i.e. IFoo** ppObj ), that means the callee is giving you back an interface and now that you have it, it is still your responsibility to call Release() whenever you are done with it.
Once you get the hang of it, I'd suggest you start using CComPtr smart class for storing local and member variables (still pass raw interface values between function calls, no need for smart pointer parameter types). It will take care of all your reference counting. Also don't make it a practice of calling release "any number" of times. It might work today because the object is implemented as a singleton, or maybe something else is holding on to it, but that might change with next patch or next release. Always follow the rules. If you have an interface, when you don't need it call Release() exactly once. If you made a copy of interface pointer, make sure to call AddRef() exactly once.
The application of addref/release semantics is much wider than COM technology. There is simple rule one CreateObject() (or CreateTexture, or GetRenderTarget, or GetBackBuffer, etc...) have to be confronted with one Release(), one AddRef() have to be confronted with one Release().
In COM IUnknown::Release() returns number of references to object. It may delude you and you can think:
"Hm... I just call Release() until it return 0 and I will have no leaks. ???? PROFIT!!!!!111" <-- That is wrong! AddRef might be called by Direct3D itself or by 3rd_party library you pass this object to, or something else outside your app. One Release for one AddRef. You should call Release when you don't need object anymore, don't waste system resources.
You said:
Calling Release any number of times on the back buffer doesn't seem to do any damage
That means nothing. May be The Universe like you so much or you just too lucky to not get exceptions from D3D.
Smart pointers (such as CComPtr) could make your life much easier if you will use them. In this case you don't need to call Release explicitly, it is called in CComPtr dtor if it is assigned to some object.
void get_surface(IDirect3DDevice9 *pDevice)
{
IDirect3DSurface9 *surf0;
IDirect3DSurface9 *surf1;
CComPtr<IDirect3DSurface9> surf2;
CComPtr<IDirect3DSurface9> surf3;
CComPtr<IDirect3DSurface9> surf4;
pDevice->GetRenderTarget( 0, surf0 ); // surface reference counter incremented, you should call Release() for this
surf1 = surf0; // surface reference count is not incremented, you shouldn't call Release() for this
pDevice->GetRenderTarget( 0, surf2 ); // surface reference counter incremented
CComPtr<IDirect3DSurface9> surf3 = surf0; // surface reference counter incremented
surf0->Release(); // release for pDevice->GetRenderTarget( 0, surf0 );
surf2.Release(); // .Release() used not ->Release() - it is important
surf4.Release(); // nothing happens because surf4 == 0
} // surf3.Release() is called in surf3 destructor
Also you may #define D3D_DEBUG_INFObefore including direct 3d headers and switch to debug d3d runtime. It is helpful in finding leaks in d3d app.
May the CComPtr Force be with you.
D3D objects are COM objects, and they use a basic reference counting system to manage the lifetime of the object. (See wikipedia for more info about the Component Object Model, or the MSDN article Managing Object Lifetimes)
The reference count is modified purely through the AddRef/Release methods, and certain other functions call those methods.
Creating the object as well as calling certain Get methods that return an object derived from the IUnknown class will call AddRef internally to increment the reference count, so you will need to call Release for each call when you are finished with the object.
If you pass the object to another function or class that stores a copy of the point (even temporarily) that class/function should call AddRef to ensure that the object is not freed while it is using it (and Release to signal it is done).
When the reference counter reaches 0 from a call to Release the object is signalled that it may be a good time to delete the held resources, but it may not happen immediately. There is also no protection for calling Release multiple times. The reference counter will not become negative, but it will not perform any other sanity checking (because it can't really) so you can cause application instability by trying to release references you don't hold.
Yes, you are correct. This is called reference counting and it ensures that objects are alive as long as they are being used, and no longer. You can use a variety of smart pointers to enforce this rule- both shared_ptr and (C++11) unique_ptr allow for custom deleters to call Release(). This makes it easy to control the lifetime of Direct3D objects just like you would for any other object in your application. You don't need to start including ATL libraries and CComPtr to use smart pointers with COM interfaces.
I have created a COM componenet named as Test.dll in that I have created an interface IDiscover.
Now i came to 2 ways of allocating the memory as
IDiscoverPtr id(__uuid(TestClass)); and Test::IDiscover *id=NULL;
What is the differnce between these two....Any Information is appreciated..
First one is a Smart Pointer and the Second one is a normal pointer.
You don't need to worry about Releasing a Smart Pointer whereas you have to explicitly Release() a normal COM Interface Pointer.
For more details on Smart Pointers, Look Here
Apart from that, the first one will try to find a GUID from registry for your Class named TestClass and will try to create an Instance of this class through CoCreateInstance API Call. It will try to get the IDiscover interface pointer through the said CoCreateInstance call and will throw an error if it fails to do so. On successful execution of the line IDiscoverPtr id(__uuid(TestClass));, you should have a valid IDiscover interface pointer in id.
The Second one is simply declaration of an Interface pointer, nothing else. You will have to instantiate it yourself through (most of the times) CoCreateInstance or one of it's variants.
The first variant is a smart pointer, the second one is a raw (ordinary pointer). The smart pointer will call IUnknown::Release() of the connected object when it itselft goes out of scope. The raw pointer will not do so and you will possibly get a memory leak unless you call IUnknown::Release() of the conected object explicitly at a suitable moment.
The first variant will try to instantiate the COM object upon its own construction (since you use the constructor parameterised with the class id) and throw an exception if that can't be done. See sources for _com_ptr_t (comip.h) for details. The second variant will give you a pointer initialized to null - not connected to any object.
Smart pointers for COM objects have a set of member function useful for instantiating objects and calling QueryInterface() - this can often reduce the amount of code needed to write. With a raw pointer you will have to call CoCreateInstance() with a handful of parameters most of which you will set to default values and this will force you to write more code. Again see the comip.h for the full sources of _com_ptr_t - they are quite readable.
The general recommendation is to use smart pointers unless you have real reasons to do otherwise.