The articles mostly compare CORBA to COM and show why providing a reference counted server object lifetime management system is harder than it appears.

1 - CORBA - Reference Counting. Adding reference counting to CORBA objects isn't as easy as it first seems.

2 - CORBA - More Reference Counting. Although we managed to develop a working solution in the first CORBA reference counting article the results were ugly and fragile. In this article we attempt to clean things up a little and, in doing so, get intimate with the Portable Object Adapter and its Servant Managers.

3 - CORBA - Reference Counting Issues. At the end of the second article we have developed a self contained reference counting implementation that appears to work. Unfortunately, it's still far from reliable as CORBA doesn't provide the level of support for reference counting that's built into COM. In this article we discuss the problem and the various CORBA methods for controlling server object lifetime.

4 - CORBA - Enumeration. CORBA provides sequences as a way of returning collections of items from an method call. The problem with just using unbounded sequences is that the client has no control over how many items it receives as a result of the call. COM gets around this problem using the IEnum style interfaces that allow a client to control how it accesses the items in a collection.

5 - CORBA - Iteration. A CORBA style method of enumeration can be seen in the iteration interfaces on the CORBA Naming Service. Given the code we've already written for the enumeration interface we can easily implement an iteration interface as well as (or, more likely, instead of).

6 - CORBA - The Evictor Pattern. Since CORBA doesn't really support reliable reference counting implementations we'll compare one of the recommended methods of servant life-time management with our reference counted iteration interface.

7 - CORBA - Keep Alive. One way of making a reference counted implementation more robust is to run the keep-alive protocol yourself. We demonstrate this option here.

8 - The CORBA Evictor Pattern in Java. In part 6 we solved the problem for C++ servers, here we do the same for Java servers.

The Secure Sockets Layer (SSL) is used by every commercial web browser and server to secure web traffic. Every time you use a URL that starts https://, you're using SSL. Microsoft provides an implementation of SSL via the SChannel API, but it is a low-level API that is quite complex to use. OpenSSL is a higher level, open-source alternative that allows you to easily add the security of an SSL connection to TCP/IP clients and servers. However, since the OpenSSL code has a UNIX heritage, most of the examples available assume a UNIX-style sockets architecture. The preferred Windows architecture of asynchronous sockets doesn't fit well with this, and this article presents an "asynchronous connector" for OpenSSL that allows you to use OpenSSL in a way that is more appropriate on the Windows platform. The resulting connector can be used with MFC's CAsyncSocket for client-side use and integrates well with server code that uses IO Completion Ports. Due to the original design of the OpenSSL toolkit, the connector can be built without having to change any of the OpenSSL code and so is standalone and easy to maintain.

OpenSSL

The OpenSSL Project is a collaborative effort to develop a robust, commercial-grade, full-featured, cross-platform, and open-source toolkit implementing the Secure Sockets Layer (SSL v2/v3) and its successor, Transport Layer Security (TLS v1). OpenSSL is based on the SSLeay library developed by Eric A. Young and Tim J. Hudson. The OpenSSL toolkit is licensed under an Apache-style license, which basically means that you are free to get and use it for commercial and noncommercial purposes, subject to some simple license conditions. However, one thing you should be aware of is that OpenSSL uses strong cryptography, and this falls under certain export/import restrictions in some parts of the world. You are strongly advised to pay close attention to any import/export laws or restrictions that apply to you.

The source-code distribution of OpenSSL provides many example programs that show you how to use it. There are some useful tutorials on the Web and books available on the subject (see References). The problem is that although the OpenSSL toolkit source code is cross platform, the example code tends to be written in a UNIX style, using blocking sockets and multiple threads or processes. When developing with sockets on the Win32 platform, it's common to want to use nonblocking, asynchronous sockets: The most scalable method of developing TCP server applications with Win32 is to use IO Completion Ports, which forces you to deal exclusively with asynchronous sockets; and using blocking sockets in a thread that serves a user interface is a recipe for disaster.

Although developed in C, the OpenSSL toolkit has an object-based design, with various components accessed by passing an object handle as the first parameter to the C API calls. The main object that we're interested in is the SSL object. This is where the actual SSL protocol is implemented. The developers of the OpenSSL toolkit designed the SSL object to use an abstract IO mechanism, the BIO, rather than hard coding it to use sockets. The BIO abstraction allows you to develop a BIO that suits your own needs and simply plug it in to the SSL object to run the protocol over whatever data stream you like. The toolkit comes with a BIO that works with a memory buffer, and one of the sample programs uses these memory BIOs to test the toolkit by running the protocol over memory buffers in a single process that is acting as both client and server side of the protocol. We can use this memory buffer BIO to provide an interface to the SSL object that's usable with asynchronous sockets.

The SSL object often needs to read and write to the data stream independently of your application. You may wish to perform a write, but if an SSL handshake is in progress, then the SSL object may need to perform several reads and writes before your application data can be sent. Likewise, data being received from the data stream needs to be processed by the SSL object to decrypt it before passing it up to the application but, due to the nature of the protocol, the arrival of data may require the SSL object to write to the data stream.

A Simple C++ Wrapper

Given the aforementioned information, we can begin to develop a C++ class that provides a clean interface to the OpenSSL memory BIOs that we will use to communicate with the SSL object. The object will act as a filter between the application and the socket. The interface to the class should provide read and write methods for pushing data into the SSL object, and be able to call back into the application when decrypted application data is available and when encrypted writes to the data stream are required. Since we're intending to operate in an asynchronous manner, and since the SSL object may not always be ready to process our application data immediately, we will need to be able to buffer data prior to passing it through our filter object. The buffer management will vary depending on how you want to use the filter, so rather than including it within the main filter class, we simply provide hooks so that derived classes can implement their own buffering scheme. Removing the uffer management code also allows us to see the actual code required to drive the SSL object more clearly.

COpenSSLConnectorBase provides the derived class with methods to push data into the SSL object. Unencrypted application data is pushed through the SSL object by calling DataToWrite() and will eventually emerge, ready to be written to the data stream, via the OnDataToWrite() virtual function. Encrypted data that arrives from the data stream is pushed into the SSL object by calling DataToRead(), and application data will emerge via the OnDataToRead() virtual function. Since an application write may require the SSL object to process responses read from the peer, the derived class should not call DataToWrite() and DataToRead() directly. Instead, when it has data that needs to be passed through the SSL object, it should buffer the data and then call RunSSL(). This will deal with any SSL-level data transmission and request read and write data from the derived class using the GetPendingOperations(), PerformRead(), and PerformWrite() virtual functions. GetPendingOperations() simply returns two boolean values that are set to True if the derived class has read or write data buffered and ready to pass to the SSL object. When the read or write data is required, PerformRead() or PerformWrite() will be called. These should call DataToRead() or DataToWrite() as appropriate to pass the buffered data to the SSL object. These calls take a pointer to a BYTE buffer and the length of that buffer; they return the number of bytes consumed. The caller should then adjust the buffered data to take into account the bytes that have been consumed and returned.

Since both read and write operations can result in the SSL object generating data that must be transmitted to the peer, the actual transmission is done as part of the RunSSL() method. If, after reading or writing, there is data to be transmitted, SendPendingData() is called and this extracts the data from the SSL's output BIO and calls OnDataToWrite() to pass it to the derived class for writing to the data stream.

CAsyncConnector is a class derived from COpenSSLConnectorBase that provides an example of simple buffering and integrates the SSL object with the MFC CAsyncSocket class.

The AsyncClient sample code puts all of this together in a simple adaptation of the Microsoft sample code detailed in Microsoft Knowledge Base, Article Q192570. The client presents a dialog interface that allows you to enter a server name to connect to and a URL to retrieve. The application connects to the specified server on port 443, the port commonly used for HTTPS servers, and sends an HTTP Get request for the specified URL. The results are displayed in an edit box. By stepping through the code and watching the debug traces, you will see the SSL connection established and the encrypted request sent. The results arrive asynchronously and are pushed through the SSL protocol to decrypt them before displaying them in the edit box.

Obviously, it would be easier to use the WinInet functions if you actually wanted to write a simple HTTPS client. The example does not attempt to validate the server's credentials or force the client to require a certificate or dictate which cipher suite to use; all of this is possible and you should consult the OpenSSL samples for details of how to use its more advanced features. The example simply demonstrates the ease at which OpenSSL can be integrated with CAsyncSocket. Using these techniques with the OpenSSL toolkit, you can easily protect any data stream with SSL.

A Potential For Optimization

The OpenSSL toolkit BIO interface includes a method of accessing the internal BIO data buffer directly, rather than passing in a new buffer for the data to be copied into or out of. This interface is exposed via the BIO_nread/nwrite methods. Unfortunately, only the BIO_pair BIO implements these methods. A BIO_pair could be used in place of our two memory BIOs and would allow us to extract data directly from the BIO in DataToWrite() and SendPendingData(); however, doing so complicates the example and so is left as an exercise for the reader.

Building the Sample Source Code

To build the sample source code you need to have OpenSSL installed; see the OpenSSL web site for details of how to obtain and install the toolkit. Once you have installed OpenSSL, you need to adjust the sample project so that it can find the toolkit headers and libraries. In the project settings dialog, on the C/C++ pane, in the Preprocessor category, change the additional include directory from "I:\openssl-0.9.6d\ inc32" to the include directory that is appropriate for your installation of OpenSSL. Likewise on the Link pane, in the input category, change the additional library path from "I:\openssl-0.9.6d\out32dll" to something more appropriate.

References

• The OpenSSL web site: www.openssl.org.
• Network Security with OpenSSL. John Viega, Matt Messier, and Pravir Chandra; O'Reilly, 2002, ISBN 0-596-00270-X.
• SSL and TLS: Building and Designing Secure Systems. Eric Rescorla; Addison-Wesley, 2001, ISBN 0-201-61598-3.
• Microsoft Knowledge Base Article-Q192570. Message-Oriented TCP and Multithreaded Client/Server.

Download

The following source was built using Visual Studio 6.0 SP5. See above for other requirements.

SSLAsyncClient.zip - the sample code

Revision history

• October 2002 - Initial revision - published in Windows Developer Magazine.
• 4th November 2002 - Article reprinted on www.jetbyte.com
• 4th November 2002 - Fixed a bug in COpenSSLConnectorBase::DataToRead()
• 4th August 2005 - Article reprinted on www.lenholgate.com

Note: If you need high performance SSL over TCP/IP then this is available as an optional part of The Server Framework; see here for details.

Registering for notifications
Suppose we want to use a COM object that provides notifications via Connection Points, the NetMeeting Conference Manager object for example. Our application will create an instance of the Conference Manager object and manipulate it via its interface, we will monitor the events it generates by registering a connection point to receieve events generated by the INmManagerNotify interface. The INmManagerNotify interface is shown below:

   interface INmManagerNotify : IUnknown
   {
      typedef [unique] INmManagerNotify *LPNMMANAGERNOTIFY;
   
      HRESULT NmUI(
         [in] CONFN uNotify);
  
      HRESULT ConferenceCreated(
         [in] INmConference *pConference);
  
      HRESULT CallCreated(
         [in] INmCall *pCall);
   }

We don't want to use MFC or ATL and the resulting program will be a console application using straight C++ and COM client APIs. Our problem is that our application simply uses COM, it doesn't expose any COM functionality itself and we don't want to add the complexity of being able to serve real COM objects simply so that we can consume events from a Connection Point. What we'd like to do is simply implement the methods of the notification interface and ask the Conference Manager object to call us when notifications occur without worrying about the necessary plumbing.

A reusable, self contained, notification class
The work involved to hook up a connection point is fairly straight forward and MFC and ATL could both provide some help if we were using them, but since we're not we have to do the work ourselves. Given the IUnknown of a connectable object we need to obtain a pointer to its IConnectionPointContainer interface and from that obtain a pointer to the required connection point interface. Once we have that, we simply call the Advise() member function, pass our sink interface and keep hold of the cookie that is returned as we need it to disconnect. If we wrap this work in a class we can make sure that we disconnect in the destructor. The class might look something like this:

   class CNotify 
   {
      public :
  
         CNotify();
         ~CNotify();
  	   
         void Connect(
            IUnknown *pConnectTo, 
            REFIID riid, 
            IUnknown *pIUnknown);
  
         void Disconnect();
  
         bool Connected() const;
  
         private :
  
            DWORD m_dwCookie;
            IUnknown *m_pIUnknown;
            IConnectionPoint *m_pIConnectionPoint;
            IConnectionPointContainer *m_pIConnectionPointContainer;
   };

Connecting can be as simple as calling Connect() and passing the connectable object, the IID of the connection point that we wish to connect to and our sink interface. Disconnecting is equally easy.

The class above is useful but it doesn't solve our problem. We still need to have a COM object to pass as our sink interface and we don't have one, or want to build one. However, it's relative easy to put together a template class that's derived from our CNotify class and fills in the missing functionality. The template looks something like this:

   template <class NotifyInterface, const GUID *InterfaceIID> class TNotify : 
      private CNotify, 
      public NotifyInterface
   {
      public :
  
         void Connect(IUnknown *pConnectTo)
         {
            CNotify::Connect(pConnectTo, *InterfaceIID, this);
         }
  
         using CNotify::Disconnect;
         using CNotify::Connected;
  
         // IUnknown methods
         ULONG STDMETHODCALLTYPE AddRef()
         {
            return 2;
         }
  
         ULONG STDMETHODCALLTYPE Release()
         {
            return 1;
         }
  
         HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, PVOID *ppvObj)
         {
            HRESULT hr = S_OK;
  
            if (riid == IID_IUnknown)
            {
               *ppvObj = (IUnknown *)this;
            }
            else if (riid == *InterfaceIID)
            {
               *ppvObj = (NotifyInterface *)this;
            }
            else
            {
               hr = E_NOINTERFACE;
               *ppvObj = NULL;
            }
  
            return hr;
        }
   };

TNotify is used as a base class for your notification sink object, it derives from the sink interface that you want to implement and provides the IUnknown methods for you. You simply have to implement the sink interface methods and then call Connect() and pass the connectable object that you wish to connect to. Your sink object
might look like this:

   class MyConferenceManager : private TNotify<INmManagerNotify, &IID_INmManagerNotify>
   {
      public :
   
         HRESULT STDMETHODCALLTYPE NmUI(CONFN confn)
         {
            return S_OK;
         }
   
         HRESULT STDMETHODCALLTYPE ConferenceCreated(INmConference *pConference)
         {
            return S_OK;
         }
   
         HRESULT STDMETHODCALLTYPE CallCreated(INmCall *pCall)
         {
            return S_OK;
         }
   };

You need to be aware of a few things when using your sink object. The first is that the COM object that is constructed for you by the TNotify base class expects to reside on the stack, or, at least, it doesn't expect COM to manage its lifetime (notice the implementation of AddRef() and Release()). Secondly the sink object maintains references to the connectable object's interfaces, so that it can disconnect when you call Disconnect() or, if you don't, when it gets destroyed. Finally, since the sink object could make COM calls when it is destroyed you need to make sure that COM is still initialised at that point - so no calling CoUninitialize() before you destroy your sink object.

The example code
The example code is slightly more complex than that shown above. Because of all the type mapping that you tend to have to do to call COM methods from straight C++ we tend to wrap the COM objects in thin C++ wrappers. We do this with the interface that we obtain for the INmManager object and we use the same wrapper to sink the events. This leaves us with a single C++ object that exposes both the INmManager interface which translates the argument types to C++ friendly types and throws exceptions on method failures, and also exposes the INmManagerNotify interface to notify us of events that occur on the object. As you'll see, creating and using the NetMeeting Conference Manager COM object and wiring it up to receieve notification events is as simple this:

   class MyConferenceManager : public CNmConferenceManager
   {
      public :
      
         // implement some or all of the INmManagerNotify methods to do stuff when the notifications happen...
   };
   
...
   
   if (MyConferenceManager::IsNmInstalled())
   {
      MyConferenceManager confManager;
   
      ULONG options = NM_INIT_NORMAL;
      ULONG capabilities = NMCH_ALL;
   
      confManager.Initialize(options, capabilities);
   
... 

Since the CNmConferenceManager object implements all of the notification interface and just does nothing, i.e. it returns S_OK to all methods, our derived class can choose to simply override the notifications that it wants to handle. Creating our object initialises COM, so that COM remains initialised until our object is no more, creates the NetMeeting Conference Manager COM object and connects up the notification sink. We can then simply call methods on the object and recieve notifications back.

Download
The following source was built using Visual Studio 6.0 SP5 and Visual Studio .Net. You need to have the Microsoft NetMeeting SDK installed. This is available from here or as part of recent versions of the Microsoft Platform SDK.

COMNotify.zip - an example notification sink using the NetMeeting Conference Manager COM object.

Revision history

• 30th May 2002 - Initial revision at www.jetbyte.com.
• 20th September 2005 - reprinted at www.lenholgate.com.

Interface design: Object creation
The factory object exists so that you can create and configure the mailslot objects as a one step process. COM objects cannot have the equivalent of C++ constructors so without a factory object you would have to create the mailslot object and then configure it. If you neglected to configure the object, or if you attempted to configure it but the configuration failed, you could end up with an object which exists within your program but is useless. It's far better to prevent the creation of these zombie objects by wrapping the creation and configuration of an object into a single step. If this succeeds then you have your object and it's correctly configured and operational, if it fails then you never get given an object.

The factory object's interface IDL looks something like this:

   interface IMailslotFactory : IDispatch
   {
      HRESULT CreateClientMailslot(
         [in] BSTR name, 
         [in, optional] VARIANT computerOrDomain, 
         [out, retval] IClientMailslot **ppSlot);
  
      HRESULT CreateServerMailslot(
         [in] BSTR name,
         [in, optional] VARIANT maxMessageSize,
         [in, optional] VARIANT readTimeOut,
         [out, retval] IServerMailslot **ppSlot);
  
      HRESULT CreateAsyncServerMailslot(
         [in] BSTR name, 
         [in, optional] VARIANT maxMessageSize, 
         [out, retval] IAsyncServerMailslot **ppSlot);
   };

The factory object itself is marked as 'appobject' which means that these methods are available for use within VB without specifying an object reference explicitly, allowing code such as this to be written:

   Dim slot As JBCOMMAILSLOTLib.ClientMailslot
  
   Set slot = CreateClientMailslot("MySlot")

Each method creates and configures the corresponding mailslot object. If the configuration fails then no object is returned and an error is raised.

Internally the object factory works by creating an instance of the COM object required but requesting an 'initialisation' interface rather than the normal client facing interface. The initialisation interface doesn't need to be exposed in the IDL or type library as it's only for internal use within the component.

The initialisation interface for the ClientMailslot object is defined as follows:

   class __declspec(uuid("589E7114-50EE-4598-9140-92610D9BC20F")) IClientMailslotInit;
   
   class ATL_NO_VTABLE IClientMailslotInit : public IUnknown
   {
      public :
   
         STDMETHOD(Init)(
            /*[in]*/ BSTR name,
            /*[in]*/ VARIANT computerOrDomain) = 0;
   };

The object factory passes the user supplied parameters through to the ClientMailslot which can attempt to configure itself. Failure results in the factory destroying the ClientMailslot and returning the error to the caller.

If object initialisation succeeds the factory queries the ClientMailslot for its client facing interface, IClientMailslot, and releases the initialisation interface. The ClientMailslot is then returned to the caller as a completely initialised and operational object.

To prevent the user creating an object directly, rather than using the object factory, the other objects are marked as noncreatable in their IDL, also notice that the IDL doesn't mention the initialisation interface.

   [
      uuid(30A92485-94D2-4CBA-AC32-EF276B7F777B),
      helpstring("ClientMailslot Class"),
      noncreatable
   ]
   coclass ClientMailslot
   {
      [default] interface IClientMailslot;
   };

The ServerMailslot and AsyncServerMailslot are created by the factory in the same manner.

Interface design: Data transmission
Data can be sent either as a string or as an array of bytes. Likewise, data can be receieved in either format. Sending in one format does not prescribe how the server can receive the data.

The IDL for the ClientMailsot interface is something like this:

   interface IClientMailslot : IDispatch
   {
      HRESULT WriteString(
         [in] BSTR data);
  		
      HRESULT Write(
         [in] VARIANT arrayOfBytes);
   };

This can be used as follows:

   Private Sub SendString_Click()
  
      m_slot.WriteString MessageEdit.Text
   
   End Sub
  
   Private Sub SendBytes_Click()
  
      Dim stringLength As Integer
      stringLength = Len(MessageEdit.Text)
  
      Dim bytes() As Byte
  
      ReDim bytes(stringLength)
  
      Dim i As Integer
  
      For i = 0 To stringLength - 1
         bytes(i) = Asc(Mid(MessageEdit.Text, i + 1, 1))
      Next i
  
      m_slot.Write bytes
  
   End Sub

Note that by sending a string you are actually sending the Unicode string: by sending "AAAA" as a string you actually send the follwoing bytes: 0x65 0x00 0x65 0x00 0x65 0x00 0x65 0x00.

The sychronous ServerMailsot provides corresponding read methods. When a message is available it can be read either as bytes or as a string. However, calling either of the read methods will consume the current message. You cannot call Read() to read a message as an array of bytes and then ReadString() to read the same message as a string, the call to ReadString() will attempt to read the next available message. If you attempt to read a message and there is not one available within the read timeout period then an error is raised. Because the read call is synchronous your code could block in the read call for the length of the read timeout period. The read timeout is specified when you create the ServerMailslot and not on a per read basis.

The asynchronous AsyncServerMailslot delivers messages when they arrive via an event. The IDL for the event interface looks something like this:

   dispinterface _IAsyncServerMailslotEvents
   {
      properties:
      methods:
   
         HRESULT OnDataRecieved(
            [in] IMailslotData *mailslotData);
   };

and the event can be handled in VB like this:

   Private Sub m_slot_OnDataRecieved(ByVal mailslotData As JBCOMMAILSLOTLib.IMailslotData)
            
      Dim stringData as String
      stringData = mailslotData.ReadString()
   
      ' do something with the string...    
   
      Dim bytes() As Byte
      bytes = mailslotData.Read()
   
      ' do something with the bytes
   
   End Sub

The MailslotData object encapsulates a single mailslot message and should not be retained outside scope of the event handler. If you want to keep the data, extract it as either a string or an array of bytes and keep that representation. This limitation is due to how the AsyncMailslotServer object optimises the event dispatch mechanism - only one MailslotData object exists per AsyncMailslotServer and it is reused for each message that arrives.

Unlike the ServerMailslot you can call both ReadString() and Read() on the MailslotData object to receieve the same message data in either format.

Implementation issues: The CCOMMailslot helper object
Implementation of the ClientMailslot object is pretty simple. It offers only two write methods and the internal initialisation method. All of the actual work is deferred to a helper object, CCOMMailslot, which deals with the code that's common between all of the Mailslot COM objects. The only work that the ClientMailslot actually does is to extract the data from the supplied byte array.

The ServerMailslot is equally straight forward. Most of the methods are implemented by CCOMMailslot with only the Read methods requiring any work within the ServerMailslot object itself. Both Read() and ReadString() call down to CCOMMailslot::Read() and then package the resulting data as either a BSTR or a SafeArray of bytes.

The majority of the work that CCOMMailslot does is simply parameter checking and the wrapping of the Win32 Mailslot API. The only slightly complex code is to be found in the read method. Mailslots can be created with a maximum message size, in which case we know the size of the buffer required for read operations, they can also be created with an unspecified message size which accepts messages of any size. If the Mailslot was created with a maximum message size then we simply allocate a buffer large enough and use that for each read. If there was no maximum specified then we first call SizeOfWaitingMessage() to see if there is a message waiting and if so to retrieve the size of the message. If there is a message waiting we expand the size of our buffer, if necessary, so that we have enough space to read the message, we then read the message in.

Implementation issues: The CAsyncCOMMailslot helper object
Not surprisingly the most complex object is the aysnchronous AsyncServerMailslot. This object is multi-threaded and generates events when messages arrive on the Mailslot. It's generally considered unwise[1] to create multi-threaded DLL hosted COM components. However, the threads created in this component are tied to the lifetime of the AsyncServerMailslot objects so we can guarantee that all worker threads will have ceased by the time the component is to be unloaded. If you're concerned about this then the code could easilly be housed in an EXE component. I feel that the convenience of having a single dll component which includes all required proxy/stub code is worth it in this situation.

When an AsyncServerMailslot is created it spawns a worker thread which performs infinitely blocking, overlapped reads on the Mailslot handle. The worker thread blocks waiting for either the read to complete or for its shutdown event to be signalled. When a read completes the receieved data is wrapped in a MailslotData object and the event is fired to alert clients.

Due to the "Rules of COM" the event sink must either be fired from the same thread that was used to register it or the event sink interface must be marshalled to the thread that will fire the event. Due to how ATL generates Connection Point code for us it's not practical to marshal each event sink to a worker thread to fire the event so instead we opt to fire the event from the component's main thread. To fire the event from the component's main thread we need to have the worker thread communicate with the main thread, one method of doing this is to use window messages another is to marshal an interface from the main thread to the worker thread. The window message method is explained in one of Microsoft's knowledge base articles[2] but requires us to create a dummy window and add other clutter to our code, the interface marshalling method is slightly more complex but offers us some advantages.

When an object needs to operate in a multi-threaded way and needs to call back into itself via COM it should marshal an interface to the worker thread using CoMarshalInterThreadInterfaceInStream(). Inside the worker thread the interface is unmarshalled using CoGetInterfaceAndReleaseStream() and can be used to safely communicate with the component's main thread via COM. This works fine until the time comes to unload the component. Unfortunately by marshalling the interface within the component you have created a circular reference cycle. The component is, essentially, holding a reference on itself and this outstanding reference will prevent the component being destroyed. Since the internal reference will be held until the worker thread shuts down and the worker thread only shuts down when the component is destroyed you can see we have a problem.

Implementation issues: Reference cycles and weak identities
The circular reference cycle problem is generally solved using the "split identity" or "weak reference" idioms[3]. The idea is that the reference cycle is broken by a reference that does not affect the object's reference count or the object exposes a second identity (COM object) that, whilst part of the main object, doesnt affect the main object's reference count. Both of these techniques allow the main object to begin shutdown when all external references have been released. Weak references are fairly complex to achieve within ATL and although a solution is presented in [3] it's overly complex and invasive for what we need here.

Our solution to the reference cycle generated by the interface that we're holding in the worker thread is to create a weak identity for the AsyncServerMailslot. This weak identity supports the interface that is required to communicate between the worker thread and the component's main thread. The weak identity is a simple COM object in its own right, it has its own implementation of AddRef(), Release() and QueryInterface() and, since the IUnknown interface returned is different from the main object it has its own identity in COM.

The IDL for the interface that we use for communicating between threads looks like this:

   interface _AsyncServerEvent : IUnknown
   {
      HRESULT OnDataRecieved();
   };

Essentially it's just a way for the worker thread to "prod" the main thread. This interface appears in the IDL file because although we only use the interface internally and none of the publically visable objects expose the object we need to have proxy/stub code generated for it.

The weak identity we need looks like this:

   class CAsyncServerEventHelper : public _AsyncServerEvent
   {
      public :
  
         CAsyncServerEventHelper(_AsyncServerEvent &theInterface);
  
         STDMETHOD(OnDataRecieved)();
  
         // IUnknown methods
         ULONG STDMETHODCALLTYPE AddRef();
         ULONG STDMETHODCALLTYPE Release();
         STDMETHOD(QueryInterface(REFIID riid, PVOID *ppvObj));
   
      private :
   
         _AsyncServerEvent &m_interface;
   };

and is implemented like this:

   CAsyncServerEventHelper::CAsyncServerEventHelper(_AsyncServerEvent &theInterfce)
      :  m_interface(theInterfce)
   {
   } 
   
   STDMETHODIMP CAsyncServerEventHelper::OnDataRecieved()
   {
      return m_interface.OnDataRecieved();
   }
   
   ULONG STDMETHODCALLTYPE CAsyncServerEventHelper::AddRef()
   {
      return 2;
   }
   
   ULONG STDMETHODCALLTYPE CAsyncServerEventHelper::Release()
   {
      return 1;
   }
  
   STDMETHODIMP CAsyncServerEventHelper::QueryInterface(REFIID riid, PVOID *ppvObj)
   {
      if (riid == IID_IUnknown || riid == IID__AsyncServerEvent)
      {
         *ppvObj = this;
         AddRef();
         return S_OK;
      }
     
      return E_NOINTERFACE;
   }

Our main COM identity has a member variable of type CAsyncServerEventHelper which it initialises with a pointer to itself (this) in its constructor. It then marshals the weak identity's _AsyncServerEvent interface to its worker thread, this creates the appropriate proxy so that calls to the interface are marshalled across threads correctly, but it doesn't affect the reference count of the main identity.

When the worker thread reads data from the Mailslot it calls the OnDataRecieved() method of the interface that it unmarshalled, this causes the call to be marshalled into the component's main thread where the helper object passes the call on to the main object. In this example we don't bother to pass any data across in the call, we just use it as a way of having one thread "poke" another. The worker thread reads data into the read buffer and pokes the main thread, the main thread then uses the data that has just been read and fires the events in all connected clients. At first this may look dangerous, but we're using the sychronous nature of the STA apartment of our main object to provide synchronisation across the call. The worker thread will block until the main thread completes the event dispatch.

Of course this is but one way of implementing a weak identity, but it's relatively simple, unobtrusive and works well.

Conclusions
Designing COM components that integrate well with VB is fairly straight forward if you follow some simple rules when desiging your interfaces.

Working with asycnhronous events is easy if you follow the rules of COM, are aware of when you're creating reference cycles and know how to break them.

References

• [1] Effective COM: 50 Ways to Improve Your COM and MTS-based Applications (Object Technology S.) - Item 32
• [2] Q196026 - PRB: Firing Event in Second Thread Causes IPF or GPF
• [3] COM IDL & Interface Design - Chapter 5

Download
The following source built using Visual Studio 6.0 SP5. Using the November 2001 edition of the Platform SDK.
JBCOMMailslot.zip - C++ COM component source code and VB examples

Revision History

• 11th April 2002 - Initial revision at www.jetbyte.com.
• 2nd September 2005 - reprinted at www.lenholgate.com.

What's an AVL tree then?
AVL trees, named after the Russians, Adel'son-Vel'skii and Landis, who first defined them, are height balanced binary search trees. To be considered an AVL tree a binary search tree must satisfy only one condition: for any node, the height of the left sub-tree and the height of the right sub-tree must differ by no more than one. As nodes are added and removed one or more node may lose the AVL property and need to be re-balanced. This can be achieved by applying one of four "rotations", this is far more efficient than having to reorganise the whole tree as you would to keep a binary tree perfectly balanced. In the worst case, a search for a specific node in an AVL tree will require 45% more comparisons than a perfectly balanced binary search tree. Whilst in the average case the additional comparisons required are negligable.

The four rotations...
In all of the diagrams below the node "A" is being examined for the AVL property and requires a rotation to restore it. Each rotation will return node "B" which will have been adjusted so that it meets the requirements of the AVL tree.

Rotate left

Double rotate left

Rotate right

Double rotate right

Additions of nodes deep in the tree can cause a cascading series of rotations all the way back to the root. This can be clearly seen from the test harness.

An ideal "learning C++" project... (pity I didn't really use C++)
Since I was learning C++ at the time I decided to implement the index in C++ (I later converted it to C for the Unix port of the game...). Having written it I wanted to be able to store all manner of things in it, so I made it "generic". At the time the best I could do was tell the tree how big the items you were storing were and supply a comparison function. The compiler of the day didn't support templates but why my generic datatype of choice was a BYTE * rather than a void * I don't know. What scares me now is looking at the code and seeing how huge the member functions are and how much is going on. There's no use of abstraction to make things easier to understand, nothing's broken into easily digested chunks. There's lots of comments though, so it must be good ;). Also I really disliked those C++ stream things, lets stick with printf() it's nicer...

I can't remember why I use the complicated stack based method of traversing the tree. I know I wrote a version which used recursion but I think I managed to blow the stack when testing it on DOS and so switched to a method that wouldn't blow the stack...

I'd just read about using gotos to get out of horrible error situations and was trying it out. Though I believe the technique of using multiple gotos to jump to a single clean up point on error is OK I wouldn't use it often today.

I remember playing for hours with this looking for a bug that I don't recall ever finding (can't think why, when the code's so easy to read...) I seem to recall that the tree became unlinked once or twice and lost some nodes...

The test program adds letters to a tree and displays the tree as it dynamically balances. It's cute to watch.

I might sit down and write a template version that uses recursion rather than the stack climbing method employed here. We'll see.

Faster than it used to be...
Having just downloaded and run this code for the first time in forever I notice that it runs a little too fast on modern hardware. Adding the following slows it down to something that you can see...

In the code that looks like this:

#include < math.h >   // pow
#include < dos.h >     // sleep
#include < time.h >    // time
  
int count;
  
int compChar(BYTE *itemOne, BYTE *itemTwo)

#include < math.h >   // pow
#include < dos.h >     // sleep
#include < time.h >    // time
  
#include < Windows.h > // <----
  
int count;
    
int compChar(BYTE *itemOne, BYTE *itemTwo)

      //count++;
      if (count == 10) {
         fprintf(stdout,"\n%s\n",dispBufPtr);
         count = 0;
      }
      printf("\n%s\n",dispBufPtr);
  
      delete dispBufPtr;
}
#endif

Add this:

      //count++;
      if (count == 10) {
         fprintf(stdout,"\n%s\n",dispBufPtr);
         count = 0;
      }
      printf("\n%s\n",dispBufPtr);
  
      delete dispBufPtr;
      ::Sleep(500);       // <----
}
#endif

Download
The source was originally built with Borland C++ v3.1 but it compiled up straight away on VC++ v5.0.

GAVL.zip

Well, that's how the "Rooms" project started. It never did generate any scripts and after a while I decided that it might be fun to write my own multi-user game and "Rooms" became ELGAR - Endless Lands Games And Realities, my multi-user adventure game language project.

The code presented here is the last version of the Rooms source code. This was version 1.7 and by this point most of the pretence of just writing a room editor for MUD II had been dropped and I was already experimenting with adventure game ideas.

The code is rather horrible, but, I was young, and it was my first C program, albeit version 1.7 of it...

The data for the "game" are stored in the various MN.* files, you can alter these with a text editor though there is a limit to the number of rooms, objects and messages that you can have. I did know the format for these files at one time, but can't for the life of me remember that now... I'm too scared to look into the code to find out.

Things I'm still quite proud of...
Objects and "features" are "wrapped" into the room descriptions. This was pretty much unheard of at the time. Small objects often appear early on in the room description and don't show in up at all if you do a "quick look" (ql) but you can still pick them up. Also, most things mentioned in the room descriptions can be touched etc e.g. the ladder, stairs, racks, forge etc. You can open/close and put things in the forge even though it looks like it's part of the room description. This was all very unusual for this kind of game back in 1989.

Try Examining things, the scabbard and Longsword (ls) are nice, take the ls from the scabbard and examine it whilst holding it, then drop it and examine it. Find the chest and examine it when shut, when held, and when open... Then try the safe... Things like drop 1 gold coin, and put fifteen ingots in the oak chest work, as I remember, but the parser can be easily fooled, try playing with the war axe, I think you can call it all kinds of things "bladed large handled axe" etc most of which aren't supposed to work...

There's a where spell, oh, the trap-door in the eastern end of the cellar is nice. Check the description when closed and again when open, go outside and close it and it's "hidden". You're supposed to be unable to open it from that side, but I never got around to that.

Things like the ingots, coins etc have different descriptions for single and multiple instances of them, try g iron ingot, dr 1 ingot, ql,dr 1 ingot,ql

Commands can be strung together n,n,n,n etc you can't repeat a command with a single period though (n....), then again, MUD II didn't do that at the time of my writing Rooms...

As you can see from the commands and the SCore it was slowly turning into the dry run for a multi-player thing. Try out the various types of personae, I never did get around to setting an "opening size" for the doors, so the giant can go anywhere and carry everything - except features - and the fairy can carry very little - a tarot card only, I think...

Anyway, download, unzip, run the batch file to run the game and don't be too harsh on the lack of quality of the C code...

Download
The source for Rooms v1.7 was for DOS and built with Borland C++ v3.1. The code is presented "as is" in all its "my first C program" glory. The compiled executable is included just in case...

Rooms17.zip