• SoC: Playing with Doxygen

    My Boost.Process prototype is almost feature complete; the major thing that is still not included is the ability to create pipelines. I should address that as soon as possible because I'm afraid it will have some impact on the existing classes, but for now I wanted to start documenting some code. There are already 21 header files to document and doing so is by no means an easy task.In order to document the library's API I've decided to use Doxygen, a documentation system for multiple languages including, obviously, C++. Doxygen scans your source files looking for special comments that document classes, methods and any other part of the code. Then, the comments are extracted alongside with the code structure and are used to automatically generate reference documentation in whichever format you want (HTML, LaTeX, XML, etc.).Doxygen is widely used and nicely integrated within Boost.Build. Boost's build system automatically generates the required configuration file for Doxygen (the Doxyfile) and lets you merge the resuting files with your other BoostBook (or QuickBook) documents painlessly.So far I like this tool very much. Keeping the documentation alongside the source code helps in keeping it consistent and makes it immediately available to the curious developer reading the code. Furthermore, it provides tags to format anything you can imagine: preconditions, postconditions, thrown exceptions, results, etc.The results? Take a look at the Reference section in the Boost.Process' manual ;-) At the moment of this writing only the classes in the detail subdirectory are documented, which correspond to sections 5.10 through 5.13. [Continue reading]

  • SoC: Status report 2

    Another week has passed and I'm happy to announce that the Boost.Process prototype is now completely ported to the Win32 API. In other words, a program can use the current library to transparently manage child processes both from Windows and Unix systems.There are still several rough edges and incomplete classes but the code passes the test suite on both systems :-) OK, you know that passing a test suite does not mean that the code is correct; it only means that it complies with the existing tests. So... more tests are needed to spot the existing failures.I'm now going to clean up some parts of the code that make little sense after the huge rototill to port the code to Win32; basically, the internal pipe class and its usage. Then, I'll try to complete the missing Unix-specific bits.Why did I say a "huge rototill"? After starting to port some code to Windows, I discovered the CRT library. For a moment, I thought that the porting could be easy, given that this supports the standard POSIX file descriptors and calls (open(2), read(2), etc.). Unfortunately, I quickly realized that using the CRT could not integrate well with the native Win32 API; and worse, I discovered that Windows only supports communicating with child processes through the three standard channels (stdin, stdout and stderr). This restriction has forced me to redo most of the existing design and code to offer a clean and common interface on both platforms; file descriptors are now hidden all around unless you explicitly want to see them.Of course this means that the classes used to launch child processes now only accept these three channels, something that is not powerful enough in a Unix system. In these OSes, processes may need to set up extra communcation pipes with children to retrieve additional information (dbus and GPG come to my mind), so there shall be POSIX-specific classes that allow this interface.I would like to finish the clean up and the addition of POSIX-specific code by the end of the month alongside some simple documentation (formal code examples). The idea is to be able to publish it for informal review soon afterwards (beginning of August). [Continue reading]

  • SoC: Status report

    Mmm... SoC. Multiple things have been going on lately in my SoC project, yet I've kept you uninformed. As I already told you, my project aims to develop a C++ library for the Boost project to manage child processes; it's named Boost.Process.During June I discussed with Jeff Garland — my mentor — the general design of the library. The design is surely not final but it is a lot better than it was at its first sketches. For example: it makes use of templates where appropriate to let the user replace any part of the library with his own code (more or less). I must say he has been very patient with all my questions and has provided extremely valuable information.I also seized that month to investigate a bit the Win32 API because the library must work on Windows too. I couldn't do much more during that time because I was busy with semester's final exams. All passed by the way :-)And now to the interesting thing. I've spent the past week (almost two) implementing a preliminary prototype. It is still incomplete but has already raised many issues; you know, it is hard to get into the details (that affect the design) without coding a bit. The prototype also includes multiple unit tests to ensure that everything works, as it shall be; Boost's Unit Test Framework is a really nice tool to implement them.Browse the source code for more details. [Continue reading]

  • Fixing suspension problems

    Once upon a time I could put my desktop machine to sleep either from Windows XP or Linux. When I replaced both with Vista Beta 2, I tried to suspend the machine and saw it fail miserably; I quickly (and incorrectly!) blamed the OS and forgot about the issue. But a couple of days ago I installed Ubuntu 6.06 on the same machine and it exposed the same problems: after asking the OS to suspend the machine, everything could power down as expected but in less than a second of suspension it could resume operation.What had changed since the last time it worked and now? The only thing I could find was the keyboard and the mouse, both of which are now USB and were PS/2 before. Mmm... as a test, I pressed the suspend button and immediately afterwards unplugged both peripherals. Guess what? The machine got into sleep mode properly!So, I opened the case and looked for the two jumpers in the motherboard (an Asus A7V8X-x) that tell it which power line to use for the USB ports: +5V or +5VSB. Changing them from the former to the latter fixed the problem and suspension works fine now.Maybe it's time to try NetBSD-current to see if this feature also works in my machine... [Continue reading]