MySQL Forums
Forum List  »  Falcon

Falcon engine documentation
Posted by: Vincent Van Den Berghe
Date: July 29, 2008 01:14AM


One thing that's missing right now is documentation for the Falcon engine.
I'm talking about somthing more specific than the super-high-level overviews you find like "Falcon design review" (, or "Falcon in depth" (
I'm talking about the nitty gritty details, like the implementation of sparse bitmaps, inversion pages, filter sets, serial log details, locks and the like. I'm talking about the why and the how. You know, blueprint stuff.

What's that, I hear? Read the source code, you say? Well, Well I'm doing just that and I'm learning a lot from it. I even reimplemented some of the more interesting stuff (for me at least) in C#.
Indeed, the source code is the documentation. Problem is, it's the only documentation and as much as I like to dive in code, a lot of time is wasted because you find yourself wondering where every piece "fits". As rewarding as it is when you finally "get it", it's not always time well spent. I mean no offense.
And let's face it: there's a LOT of source code to read and a lot of complexity to master. With all due respect to the highly capable brains that work on it, the few comments you find in there don't enable you to understand what's going on unless you already understand what's going on.
And (at the risk of being incinerated by said capable brains) the code isn't exactly factored well: it's just a bunch of files in a directory and another bunch of files in TransformLib. Surely this could be refactored better: there's locking, page IO, serial log stuff, threading, SQl stuff... even the use of namespaces would help make this a more managable blob (pun intended).

The (now outdated) doxygen'd stuff you find like, is only part of the story. Automated tools don't help much. What would really help is a guiding hand.

Or maybe my brain isn't capable enough... always a possibility, of course.


Options: ReplyQuote

Written By
Falcon engine documentation
July 29, 2008 01:14AM

Sorry, you can't reply to this topic. It has been closed.

Content reproduced on this site is the property of the respective copyright holders. It is not reviewed in advance by Oracle and does not necessarily represent the opinion of Oracle or any other party.