GetQueuedCompletionStatus() – Devil in the Details!

One of the projects I work on makes use of the Win32 asynchronous I/O model for managing network traffic between a Windows Service and a custom-built network device.

One of the key Win32 APIs we use is called GetQueuedCompletionStatus. This API provides access to an I/O completion port that is managed by a separate operating system thread.

When dealing with this API and Windows asynchronous I/O in general it helps to think about the model as being supported by a separate workpool thread. This API gives the caller a way to synchronize with the operations of that workpool thread (or threads).

The prototype for this API is as follows:

BOOL GetQueuedCompletionStatus(
	HANDLE CompletionPort, 
	LPDWORD lpNumberofBytes, 
	PULONG_PTR lpCompletionKey, 
	LPOVERLAPED* lpOverlapped, 
	DWORD dwMilliseconds);

At first glance the API may not seem too complex. There are 5 parameters and a boolean return type. Some of the parameters are easy to figure out just be looking at their names. Others are less clear. You could speculate that the returned boolean is an indicator of whether or not the operation was successful or not. It is easy to be lulled into a false sense of understanding by reading through the first few paragraphs of the MSDN documentation on this API.

It actually turns out that this API is very complex (perhaps too complex?), and careful study of the MSDN documentation is required if you wish to handle all of the possible conditions when this API returns. Pay careful attention to the section in the documentation that discusses Return Values and Remarks.

My favorite gem from the return values section (and the one I recently missed when using this API) is:

If a socket handle associated with a completion port is closed, GetQueuedCompletionStatus returns ERROR_SUCCESS, with *lpOverlaped non-NULL and lpNumberOfBytes equal to zero.

In other words, when the socket is closed (possibly because the peer closed it) you will get what appears to be a successful I/O completion. This does not represent what most would consider a successful return, and if you have not carefully checked the other parameters, your code may mis-interpret this condition.

Another area where you need to be careful when using Windows Asynchronous I/O is application shutdown. There may be a number of pending I/O operations that have been queued to the I/O completion port. It is your responsibility to finish processing all of these I/O operations (possibly by first closing the socket and then handling each failed I/O completion event) and release any resources that were allocated for the I/O operations. Failing to do this will likely result in a memory leak for the application.

The moral of the story is to always read the entire MSDN documentation page and make sure your code handles all of the possible combinations of return values!

Advertisements

Apple iPhone SDK — Catch-22 for Developers

Way back on March 6, 2008 I signed up for the Apple iPhone SDK along with many other developers. Everyone watched the Apple announcement by Steve Jobs about the SDK and iTunes Application Store; everyone heard about the $99 enrollment fee for the developer program; everyone heard about the 70/30 split on application sales through the store; and most important of all, everyone heard that the store would go live toward the end of June. That was a clear signal to all developers hoping to sell applications for the iPhone or iPod Touch. The message was Start developing your applications now so they are ready in time for the grand opening.

Sadly, the reality of the iPhone Developer Program for many developers has been very different. What has actually transpired is essentially a Catch-22 for independent software developers wishing to build applications for iPhone/iPod Touch.

Many (possibly most) developers who signed up for the program on the 6th were greeted with the following message after the multi-step enrollment process:

Thank you for submitting your information.

While we process your information, please visit the iPhone Dev Center to download the iPhone SDK and access a wealth of technical resources. Please note, the iPhone Developer Program will initially be available to a limited number of developers and will expand in the coming months.

Next Steps

You will receive notification of your enrollment status. Enrollment ID: xxxxxxxxxx

No additional information was provided. No channel for posing questions about the progress in letting developers into the program was provided. No means of determining if you would even be accepted into the program before June. Nothing. Apple is dead quiet about the status.

The lucky few developers who have already been selected by Apple are all under NDA, just like everyone else who is trying to join the program. This means there is little if any information being shared by these developers regarding what Apple may be telling them about the June launch of the store.

Apple is asking us to all download the SDK and begin developing our applications using the iPhone Simulator. They are asking us to blindly trust that once we invest significant time and resources into developing these applications that we will someday be able to test them on actual devices and eventually be able to sell them in the store.

Back on March 6, 2008 Apple indicated that the number of developers in the program would expand in the coming months. It is now roughly one month before the application store is projected to “go live” and many developers still do not have the ability to test their applications on actual devices.

Apple is asking all independent software developers to risk a lot of their own resources while the developers remain in limbo. We don’t know if/when we will have the opportunity to test our applications. We don’t know if/when we will be able to get more details from Apple regarding the store. We don’t know if/when we will be able to submit applications to the store for sale.

And, to rub salt in the wounds of developers everywhere, a few days ago Apple reminded all of us that the deadline nears for submitting your iPhone applications for consideration in the 2008 Apple Design Awards held at this WWDC this summer.

You might say “So what, just submit the applications you build with the iPhone Simulator”. That would be a perfect solution but for one small problem. In the release notes for the SDK Apple mentions that some portions of the SDK code cause crashes on the simulator. They offer two methods to work around the issue. First, you can forgo using the Interface Builder tool and place your controls on the screen manually. Second, you can just do your testing and debugging on the actual device. That would be the perfect solution except we cannot load applications onto the device because we have not yet been accepted into the iPhone Developer Program.

Steve, please level the playing field for independent software developers everywhere who want to develop applications for this fantastic new platform you built. Continuing to ask independent developers to sholder so much risk and uncertainty is not what we expect from the company that asks us to Think Different.

Method Swizzling in Safari on Mac OS X

Recently I have been working on an extension for the Safari web browser. The biggest challenge when developing an extension for Safari is determining how to hook your code into Safari.app. Most browsers these days provide hooks to allow development of extensions, but Safari does not.

A technique that many people use to add functionality to Safari (and other Cocoa applications) is called Method Swizzling. If you want to learn more about this technique there is a terrific article explaining all the details on the CocoaDev site.

When applying the method swizzling technique you may find that the linker complains about unresolved classes and won’t link your bundle. This issue usually crops up when you try swizzling a method that is in a class you learned about by running class-dump or by using FScript. If you run into this problem bring up the project properties in Xcode and add -undefined dynamic_lookup to the Other Linker Flags section.

Without this extra flag your plug-in will not link, and you will be stuck in the mud! Thanks to Aaron Harnly, author of Letterbox, for pointing this out to me in an e-mail exchange.

Young Entrepreneurs ship File Manager for Atari 800

The first computer I owned was an Atari 800. While this was not the first machine I worked on (in 7th grade I was using a TRS-80 from Radio Shack to program in Basic and was using an Apple // at a neighbor’s house to play Space Invaders), it was the first machine I had at home every day after school and all summer long!

Here is a photo of what this beast looked like. I had the main unit with keyboard, a couple language cartridges and two of the Atari 810 floppy disk drive units. I didn’t have the printer shown in the picture. Atari 800, 810 and 820. In order to program this computer I used the BASIC Programming Language. This was loaded into the computer by inserting a ROM cartridge.

The concept of a disk operating system was somewhat limited in those days. If you wanted to move files around on the floppy disks you didn’t have many options. Of course, this meant there was a golden opportunity for someone to create an application to address this shortcoming!

Shareware was all the rage back then so a friend and I set out to build an application that would help with disk management. Of course, back in those days there was no Internet, no concept of registering your domain name, or any notion of taking payments via PayPal. Nope, in those days you had modems and buliten board systems. People ran file BBS nodes using something called FidoNet. Some people had more than one dial-in phone line for their BBS systems. Most only had one phone line, and some had to shut down their BBS systems when they wanted to make phone calls.

Our plan was to build the application and upload it to FidoNet. People would get to use it for free, and if they liked it they would mail us a check for a few dollars. (Yes — using the postal service, a stamp, and a real paper check.) The application was called Disk Master and the company we founded was called Seaview Software.

I don’t have a copy of the software anylonger but did run across a copy of the documentation for our first release.

Cheers!

Rubic’s Cube Solution

Way back in 1980 I spent the year in Munich, Germany going to school. I was in 9th grade at the time and attended an international school South of Munich. During that year the Rubic’s Cube became popular and I like many other school kids had one. It took me a while to figure out how to manipulate the cube in order to complete one side (all nine squares had the same color on that side). Of course, the goal was to figure out how to complete all six sides. Working with friends I eventually figured out how to get most of the cube back to the “factory default” configuration. My friends and I never did figure out how to get the last few pieces into place. To get the last bit of the solution we had to look in a magazine where a solution was published.

I returned to the United States for 10th grade. In my English class we had an assignment to write a technical paper that explained how to perform some task. I decided to write down the solution for the Rubic’s Cube. The attached PDF file contains that solution.

Now, 27+ years later I look back at that writing and can see that even at that young age I was a real sarcastic little sh*t. The whole paper is just dripping with sarcastic remarks. Wow! Not a lot has changed in all these years. I’m not sure that is a good thing, but at least I recognize it for what it is.

Enjoy the solution – I hope it helps you solve the Rubic’s Cube if that is your goal.

Cheers!