Effective COM

Here are my crib notes for "Effective COM: 50 Ways to Improve your COM and MTS-based Applications" by Don Box, Keith Brown, Tim Ewald, and Chris Sells, from Addison Wesley, 1999.

Remember how Meyer's "Effective C++" book stopped you from using about two-thirds of the gimmicks explained in earlier books? "Effective COM" will stop you from imitating at least 90% of the COM you see elsewhere. Only after reading this book did I feel I had any hope of achieving good style with COM.

§    Lessons

Here are some lessons I learned, although not necessarily as the authors intended.

• Implement a singleton with a static class member. Provide interface methods that use this static member. Do not attempt to return interfaces as singleton instances. (Item 4.)
• Forget about using exceptions. Every known emulation is worse than simply checking error codes. You can't throw an exception more than a few lines within a single method, and you'll find it harder to know which resources to release. (Item 5.)
• Don't return E_NOTIMPL from unimplemented methods. Use smaller interfaces that can be implemented completely. (Item 7.)
• Don't pass data through IDataObject. For type safety, define a unique interface for each type of data. To avoid race conditions, return related pieces of data together in a structure or from a single method call. (Item 8.)
• Feel free to use a COM interface to negotiate a separate non-COM connection, such as a socket. (Item 8.)
• Don't use connection points. Define your own observer and observable interfaces. (Item 9.)
• Don't use tear-off interfaces. Clients may get new implementations of an interface when sharing an apartment with your object, but they may get a previous stub if they live in a different apartment. (Item 10, 26.)
• Don't use per-interface reference counting. Proxies will not necessarily notify you when individual interfaces are released. (Item 10.) Instead use multiple COM identities with shared state in the implementation. (Item 26.)
• With VB script, you're stuck with one interface per object. Forget about polymorphism or type safety. Don't let this environment degrade the rest of your framework design. Only expose the highest-level user functionality for customers who demand scripting. (Item 11.)
• Avoid dual interfaces. Don't require them in callbacks (observer interfaces) because you'll call only one of the two implementations anyway. (Item 12.)

  Implement IUnknown exclusively to share components with other C++ or VB developers. Implement IDispatch very selectively for customers who can't manage anything other than VB scripting. The book's Epilogue says "Curse the Visual Basic team for the abomination that is IDispatch."

  Remember "Visual Basic programmers can still implement externally defined pure vtable and pure dispatch interfaces" although they can only define new interfaces as dual interfaces. It's not your problem.

• Use size_is when passing arrays, but don't use first_is or length_is. Instead, pass a shifted array pointer. (Item 13)
• Don't pass statically-typed IUnknown object references because proxies and stubs won't always give you the one you want. Use iid_is to specify the exact interface. (Item 14.)
• Don't use [in,out] parameters that contain pointers because you won't know what resources to release after a failure. Use two separate [in] and [out] arguments. Rethink how you pass structures that contain pointers. (Item 15.)
• Weak references (holding an interface pointer without calling AddRef) won't work across apartment boundaries. The proxy will disappear. (Noticing a pattern here?) (Item 16.)
• To avoid circular references, you can instantiate two COM entities in the same apartment. These two communicate without AddRef's. One will be AddRef'd by third parties, and one will call AddRef on those same third parties. (Item 16.)
• Don't use IDL commands wire_marshal, transmit_as, call_as, and cpp_quote to alias data types or methods. They aren't handled properly by type libraries. (Item 17.)
• Set [out] parameter pointers to null if you return an error. (Set *ppThing=0.) Stubs will ignore your HRESULT and marshal non-null [out] parameters anyway. (Item 18.)
• Rediscover how to manage memory robustly in plain C, with MS versions of malloc and free. A method that safely copies a string should take a page of code. Check that callers provide non-null [out] pointers to pointers. Before returning an error, free the memory of [out] parameters. If allocation fails, return E_OUTOFMEMORY. (Item 19.)
• Set interface pointers to null immediately after releasing them. Use a macro if necessary. (Item 20.)
• Remember that COM interfaces use non-virtual destructors. Before deleting a C++ object that implements a COM interface, you must recast to the original most-derived class. (Item 20.)
• Call AddRef and Release immediately before and after a QueryInterface to get an interface pointer that you return from a method. Otherwise, if QueryInterface fails, the implementer of Release will have no opportunity to free resources. (Item 20.)
• A constructor for an aggregation might call CoCreateInstance to create a member with this as the controlling IUnknown*. Since you can't call Release in a constructor, you must increment the internal counter by hand at the beginning of the constructor. (Item 20.)
• When passing interface pointers to QueryInterface or Invoke, always call static_cast to the correct type, then call reinterpret_cast to the void** or void*. (Item 21.)
• The long struggle to define auto_ptr showed that heap memory cannot be managed by scoping rules as if it were stack memory. You must have read and understood the implementation of your smart pointer, to know the limitations. If you are likely to confuse maintainers of your code, then don't use smart pointers. (Item 22.)
• Don't implement every object as a COM object, with the unnecessary constraints and overhead. Expose COM interfaces only when "crossing boundaries in your system: distribution boundaries (apartments, processes, and hosts), language boundaries, product boundaries (including third-party products), and logical boundaries encapsulating subsystems and their extensibility points." (Item 25.)
• Consider lazy wrapping of numerous C++ objects as COM objects only when requested. (Item 25.)
• Avoid mixing OLECHAR* arrays and BSTRs. The C++ compiler can't distinguish their types. (Item 27.)
• You can easily live without COM aggregation and COM containment, although you'll have to deal with bugs in others' implementations. As usual, prefer containment to inheritance. Rather than make a contained interface accessible through QueryInterface, return the interface with a getSomeInterface() method. (Item 28.)
• Keep your life as simple as possible when marshaling objects between apartments. (Avoid tricky optimization.) Expect this part of the COM environment to change soon.
• Don't put interface pointers in global variables because they won't be marshaled when accessed from another apartment. Use a getSomeInterface method or put the global into a CreateStreamOnHGlobal with a CoMarshalInterface and extract with CoUnmarshalInterface. (Item 29.)
• The creator of a new thread should call AddRef on passed interface pointers, and the new thread should call Release. (Item 30.)
• UI code should run in a STA. The code isn't thread-safe, and it requires an event loop (message pump) to avoid locking the UI during time-consuming callbacks. Worker threads should run in a separate MTA. Messages to the UI should go to MTA objects, which update the UI with messages to the STA when necessary. (Item 31.)
• Use an executable server instead of an in-process server if you need to create new threads. Otherwise you will be unable to manage simultaneously the lifetime of your threads and in-process references to your objects. (Item 32.)
• The Free-Threaded Marshaler is a difficult optimization that will probably be obsolete by the time you understand how to use it safely. Go ahead and pay for the overhead of proxies between STA and MTA components. (Item 33.)
• You still have to think of synchronization issues in a STA. If you call out of a STA and want to receive a reply first, then use a IMessageFilter to postpone other calls and messages. All outward calls are placed in a new thread so that the message pump can keep the GUI alive. Unfortunately the response may arrive after other calls that want to change the state of your object. (Item 35.)
• Don't export pointers to in-process objects implemented in different DLL's. You will be unable to prevent the DLL from being unloaded while others hold references to the object. Call CoCreateInstance with CLSCTX_LOCAL_SERVER instead of CLSCTX_INPROC_SERVER. (Item 36.)
• When an object must shut down abruptly and abandon clients, then it should call CoDisconnectObject to inform the stub to release references to the object. Proxies will then return the HRESULT of RPC_E_DISCONNECTED to calls by clients. (Item 37.)

§    Editorial

This book confirms the long-standing belief that MS development tools encourage fragile and unmaintainable code. The code may still compile, but it won't be easy to upgrade or integrate with next year's code. MS will constantly change their recommended patterns, frameworks, and developer tools. The book's epilogue says "Distrust your tools. The COM group produces COM, and various tool groups at Microsoft proceed to butcher it." Remember, clean maintainable code is not necessarily in Microsoft's interest.

You should be able to justify every line typed into your COM code, without a wizard's guidance. Find a safe core subset of COM and don't use clever tricks just because they are explained in every other COM book. If you stick to the safe subset, you may not have to rewrite current code every time you reuse it.

This book, and Don Box's previous book "Essential COM", unfortunately maintain the pretense that COM is a binary standard, independent of language or platform. COM is is none of these. COM is a C++ specification for Microsoft compilers on Microsoft operating systems. With any language other than C++ you are incompatible with the design of COM. With any other compiler or platform, you can forget about binary compatibility. The binary layout of C++ vtables is not a standard. You can use parts of COM in other Microsoft languages, but those languages introduce hacks that look horrible in C++.

Stick to C++ when implementing interfaces for other Microsoft developers, and stick to the cleanest possible C++ style. If you want Java, GNU C++, or other non-Microsoft languages, then use portable connections like sockets or JNI to talk to COM proxies and clients. (J++ isn't Java, and it isn't meant to be maintainable.)

The purpose of COM is to introduce components to each other, not to dictate how they interact or exchange data. The COM specification emphasizes, "COM, like a traditional system service API, provides the operations through which a client of some service can connect to multiple providers of that service in a polymorphic fashion. But once a connection is established, COM drops out of the picture. COM serves to connect a client and an object, but once that connection is established, the client and the object communicate directly without having to suffer overhead of being forced through a central piece of API code..."

Bill Harlan, March 1999

Return to parent directory.