I expect that the reaction of most people to type safety in python would be to first ask why, and then wonder wouldn’t it make python as slow to develop in as C or Java. Worse: doesn’t it break duck-typing.

Let me answer those in reverse order:

My personal take regarding development speed is that python is good not due to how few keystrokes it requires you to enter, but from how quickly you can try out new ideas.

Number one on that front is that python is an interpreted language, so no compiler. Especially compared to C where something like a header file change can force you to sit for umpteen minutes to get results, life with python is good. Beyond that: automatic garbage collection, good string support, and a gigantic set of built in libraries all make getting real work done easy.

For me ( at least ) typing ( keystrokes ) is the least time consuming aspect of development. Even if i have to cursor around to add members to a class, that’s nothing compared with the brain time it takes me to figure out how i’m going to put together an application.

All that said, even if you were to allow that maybe a few extra keystrokes here and there ( i think it averages out to about 15 extra characters or so per parameter and class member ) might not make a significant difference in development time — the question still remains: why.

I’m a bad programmer. I make mistakes all the time. To me, types are an integral part of making sure I’m doing the right thing. To put it another way:

Types are a form of implicit unit tests.

And unit tests are good, right?

Bartleby is actually the expression of the fact that whenever I try to refactor code in python, I often spend a significant amount of time tracking errors due to parameters or class members that have changed. If those errors were caught early in a given run, rather than late: so much the better.

Last thing: duck-typing. First, imagine a long philosophical argument about the wonderful clarity of adapter classes here -> (). And, then, imagine a similar discussion about how code is mostly supported not written here -> (). Roger. So that said ; ) you can always ‘’not'’ use Bartleby where you want to allow duck typing, and you can also use Type(object,…) to allow any type.

It deserves so much more recognition than it gets, however, because it does several key things better than everything else. Unfortunately (for me) it hasn’t kept up over the years with language changes and even small things like Java attributes disturb its order so completely as to make the program unusable.

After somewhere near 12 years of use I’ve become physically grafted to it. This is great when the editor works but horrible when when it doesn’t. Due to some of the problems it has I’ve been looking for a new editor this last couple of weeks — but I still can’t find one that works the way I want.

In order to prove to myself that it’s not simply out of habit that I use Source Insight but that it still actually rocks after all these years… here’s my review.

Simple, Beautiful Features

Search results are a normal text window.

Whether you do a “find in this file” or a “find in all files” your results go into a newly created text file. Yup. Not a specialized dockable floatable window with resizable columns or buttons to click on.  Just a text window.   How emacs I know.

A few reasons why this works so well:

• You can have limitless search windows, controllable in a very standard way: just like every other file buffer.
• You can manually winnow your searches. I can’t emphasize enough just how useful it is to search for a call to a function, toggle back and forth between the search window and the actual code, delete matches that aren’t what you are looking for, append new searches, rinse repeat. Learning new code? Looking for a bug? Needing to refactor? This is a must have feature.
• You can save your searches ( they are just text files after all ) and call them up later ( though see “annoyances” below )

The closest to this is SlickEdit which does allow you to manually winnow your search but still insists on having a custom window.

The furthest away is Eclipse.  Can I ask: who thought putting search results into a tree view that you have to click through with your mouse was a good idea? It’s essentially unusable.

Why doesn’t any other professional editor copy this simple feature?

My opinion, is that I think the developers of most editors are focused on individual feature bells and whistles — they don’t see the benefits to the end user when different features use the same code and act in the same way. Source Insight seems to have limited itself to four, possibly five, control / window types — everything therefore looks the same and operates the same even though you do different tasks with them. The next feature is in this category as well.

Case intelligent syllable-based winnowing.

In every dialog where there’s a list of items: files, symbols, etc. you can winnow the list in real time by typing what you are looking for. For instance, in the file dialog: you initially see the list of all files in the project along with an edit box into which you can type. As you type the list of files is reduced to what matches the text you have typed. If you have two files: “Foo.txt” and “Fee.txt” — if you first type “F” you will still see both files, then if you type, “Fo” you will only see “Foo.txt”, if you instead typed “Fx” — nothing would show up.

Lots of programs do this these days but Source Insight was doing it ten years ago and it still manages to do it better because it didn’t stop with simple winnowing. It also uses “syllable matching”.

Syllable matching is slightly a misnomer. Basically, SI starts by separating words out of the run-together phrases that programmers use to identify variables and types. MY_GROUP, MyGroup, myGroup, and my_group, all share the three two words. If I were to type either “my” or “group” into the symbol lookup window ( and this works for files and every other list as well ) Source Insight would consider that a match and ensure that, for instance, “MyGroup” would show up in the list of possible symbols.

It goes a tiny bit further than just raw matching though. If you specify a case for the partial words that you type by mixing cases, for instance: “camelCase” or “PascalCase”, then it assumes that you are trying to give it more specific information and will limit its search to your matching case pattern. If you are unsure of the case but want to enter multiple syllables you can enter a space. A quick example of what this means, typing: “render object” in the symbol lookup might yield “renderMyObject”, “MSG_RENDER_OBJECT”, and “ObjectRenderFunction”.

Just to explain why this particular feature is one I love: i can’t tell you the number of times i can sort of remember the class name of something but not exactly. Or I need to open a file, but can’t remember exactly where it is in the file path. If i can remember some piece of the item in question — i can find it almost instantly.

Could it go further? It’d be great if it prioritized symbols by most likely match, only prioritized case based searches not actually winnowed out differently matched cases, and it’d be awesome if it remembered my recently searched items and ranked those high.

Comparisons

Visual Studio: the command window is a beautiful hidden feature.  If you can find the menu option that let’s you access it, and if you type the command “of” at the prompt, it will let you open a file using basic winnowing. Matching is case-insensitive and it doesn’t do any form of syllable matching, but still much better than clicking endlessly through project file hierarchies.  ( I know msdev can be extended with plugins and that there are a couple of really good ones out there, some that give you a special window to open files. )
Eclipse: only begins to winnow after you type something — so you can’t do searches by scrolling through lists.

Slickedit: it appears to do basic syllable matching, but truly horrible and essentially a show stopper for me: winnowing is done as a synchronous operation. If SlickEdit needs to search it stops you from typing. if you have a project with 100,000 symbols it is so amazingly slow and interruptive to use you might as well not.

The Context Window.

This is a dockable window that shows you the definition of whatever symbol your cursor is on, plus has a few lines ( the number depends on how large you make your context window ) on either side of the definition so you can see comments, and other related code.

This is very similar to SlickEdit’s preview window. Strangely neither source insight, nor slickedit allow you to copy text from this window. More strangely: slickedit lets you try, makes it seem like you succeeded, but it doesn’t actually copy the text out that you want.

SI’s implementation has two nice features:

First, you can “lock” the window so no matter what other file you open or symbol you look at the window stays at what you were previewing.

Second, for variables, the window’s focus changes over time. If you are looking at a variable, it will first show you the variable’s declaration, and then, a second or so later, the declaration of its type. I kind of wish it would keep going up through class hierarchies, etc. but still it’s very useful — you can see lots of information about any given variable without having to leave the location you are editing.  By using “lock”, if you don’t want it to go up to the type, you can stop the window after it shows the variable’s declaration.

The context window incredibly helpful when navigating code, and it also provides some of what people look for in auto-completion: what parameters can this function I’ve just typed take?

SlickEdit has a similar feature, but strangely: you can only search for symbols of text you have highlighted. Want to look up something off the cuff and you are out of luck. ( I’m sure you could write a macro in SlickC to help with this )

Smart Reference Matching.

“Symbol search” allows you to search for all uses of a symbol in a file or project — many editors have this now, but again, Source Insight has had it for quite a long time, and for several  years now has had an excellent extension: Smart Reference Matching.

This extension of symbol search attempts to limit the search to the specific instance of a symbol name that you have highlighted. If you have two classes that both have a method ShouldaNamedItUniquely() then it will attempt to limit its search to particular uses of the class you are interested in. This is amazingly invaluable for projects that really like to use short method names where you can wind up with dozens of classes that have a method called “getName()” or the like. That said it doesn’t always work perfectly — so you have to somewhat intuitively learn when you can trust it and when you can’t.

SlickEdit has search by matched color. I find it hard to activate and feel it has limited use because it just says: search for all methods called “getName” as opposed to limiting by symbol context.  I think it’s generally pretty rare for different types of symbols in a project to use exactly the same case and exactly the same word tense, and I find name duplication across types to be much more rare than within the same type.

Matched Symbol Color Coding.

Source Insight colors text not just based on what you mean the text to be, but whether name you’ve typed is valid in the context you’ve used it. This means that without compiling your code you can visually see whether a symbol you’ve used is valid in the current context or not. If, for instance, you have an instance ‘x’ of class ‘X’ with a method ‘doStuff()’, x.doMyStuff() won’t color code, but x.doStuff() will.

This doesn’t eliminate syntax all of your syntax errors completely — but it gets damn close.

That said this feature does have its ups and downs. 80% of the time it works correctly but if you’ve got files it can’t parse ( see deal breakers ) then it will fail.

Many editors have something similar — but generally you either only get basic detection of intent or you have to compile the project to get the validation.

With only basic detection things that seem like methods to the editor, whether or not the method is a valid member of the class in question get colored as a method. ( SlickEdit is in this category )

Regarding compilation, it seems like, because Java has reflection, most Java editors choose this route. They compile behind the scenes as you type. It’s better than SlickEdit — but, if you’ve got incomplete classes, or other syntax errors — a common occurrence when you’re initially authoring new code — you don’t get proper color coding.  Also it feels, to me, a little slow — but maybe that’s just Java GUI on Windows. Visual Studio also seems to do something like this compilation under the hood for C/++.

Change This Color: As an aside: SI allows you to select a colored piece of text in the editor and, in the context menu, popup the color dialog for that text colorization type. It’s a super nice way to tweak the editor.

Color Inactive Code: Also on the matching/ color front for C/++: SI allows you to define project ( and global ) conditional compiler settings — this lets SI know that the code is inactive. Although it doesn’t have code collapsing, it will grey out those blocks, and will ( by default ) ignore those blocks when you search.

File History and Auto Recovery

Every time you save a file Source Insight generates a completely new backup of your file. This has saved me from my own stupidity so many times I can’t even say. Even better, it appears to quietly auto-save to the new backup file up to the point when you manually save to your actual file. ( ie. manual save is probably: force auto-save, save-file, generate new-autosave file. ) This has saved me from the rare source insight crash, os crash, and power failure more than a few times.

Intelligent Cursor History

Just as a back button on a browser lets you move to earlier links, Source Insight tracks the history of your cursor, and lets you jump back to earlier locations. Many programs provide some basic implementation of this — but the way SI’s seems to work is that it only creates an internal bookmark if you either jumped there due to a search, edited some code, or hung out at a location for a while. This means minor movements of the cursor are collapsed in the history. Visual Studio, for instance, has a cursor history but i find it unusable because it remembers literally every movement.

Other nice stuff

Global Symbol Lookup. This is similar to Symbol Search, mentioned with Smart Reference Matching above, but instead of finding uses of a symbol, it allows you to jump to the definition of any symbol. This used to be a feature unique to SI but many editors offer this now. Source Insight still bests them due to its syllable matching.

Relation Lookup. Lets you see the hierarchy of classes, lets you choose to look up or down the hierarchy. Can display results in tree-view form or in graphical format. It’d probably has more power than I give it credit for.  I generally find it hard to change the relation I’m looking at, so i usually don’t bother with the window at all.

Parse Source Links. Using regular expressions you can turn any text file into a bunch of navigable links.

Project Add/Remove Files. Source Insight does this pretty badly. What’s amazing to me is that everyone else does this even worse. In SlickEdit, for instance, there is *NO WAY* to add a file that you have open to your project. ( I’m sure you could write this in SlickC, but still )

Add /remove files recursively by wildcard. Nice. Simple. Easy. No one else does this. You either get: recursive, or you get wildcard, but you don’t get both simultaneously.

Add any known type. Most programs have sets of wildcards for each type — Source Insight has that, but it also allows you to automatically add any file type it knows about. That’s really nice if you have a combo project made of C, xml, txt, vcprojs, html, etc. Most big projects are of this sort.

Toolbar / Menu / Key customization. All menu and keyboards commands etc. are referred to by a two part hierarchy of names corresponding exactly to the default menu layout, and the names are in plain english. For instance, the command to open a file is “File: Open” because it appears on the “File” menu with the name “Open”.

Straight forward enough? Until I used SlickEdit I didn’t realize how important this is. In SlickEdit if you want to add something you see on a menu to a key shortcut? Good luck — you’ll have to guess the command name. Same issue for popping up dialog boxes.  For instance, to get to the “open file in project” list you have to hunt down the command: “active-files” and that’s one of the less obscure commands.
As example of the simple reuse of code: you can dump all of the key bindings, menu bindings, etc. to a text file so you can see / sort for commands. Other editors invent custom navigation and search dialogs — which is nice i suppose — but spend time on actual functionality not complexity please.

Keyboard oriented but mouse friendly. You can do every operation quickly and easily with the keyboard but you can also use your mouse if you want. Most programs that are heavily keyboard accelerated generally need at least some mouse based interaction to get stuff done.  Those that don’t ( ex. emacs ) aren’t friendly at all if you want to use the mouse. Usually keyboard is the way to go, but sometimes it is just faster to click on what you can see.

Instant on. Ever opened netbeans or eclipse? It takes on the order of a minute. Good luck getting a new idea down quickly. Source Insight opens faster than you can blink even on my highly underpowered laptop ( okay ~10 seconds ). The editor doesn’t feel big and bloated. It feels light and transparent.  Unfortunately, most of the Java editors I’ve tried move like thick soup.

The Deal Breakers

User created languages are second class citizens so if Source Insight doesn’t fully support a given language: good luck. Two of the worst for me are Java and ActionScript.

Java parsing can’t handle @tags.

If you have an @tag, rather then skip the line because it doesn’t understand it — source insight’s parser eats the whole file — nothing in the file registers as a symbol after the tag. Yikes. Even better, because it’s a predefined language, you can’t create your regex interpretation of the tag to make the parser ignore it.

No action script support.

You can sort of get a good look but you can’t make it recognize the weird javascript based variable syntax well enough to truly allow good symbol lookup.

Auto-Completion is terrible

Every time you type the popup symbol / auto completion box disappears and restarts parsing. It’s also a little slow ( which is strange given how fast everything else is ). This isn’t a deal breaker for me because I don’t use auto-completion but I list it in this category because I know several people who can’t live without it.

Miscellaneous Annoying Stuff

Some searches can’t be saved. If there’s both file and line info in displayed in the search then you can save the search and reload it later; if not you can’t.

Symbol searches don’t show line numbers. I think this is a recently introduced bug — and it’s annoying. It means you can’t save symbol searches. Of course since you can’t do this in most programs anyway I guess I shouldn’t complain.

Bad colors / text sizes out of the box. No predefined palettes to swap between and the default is *crazy*. I’ve had several friends try Source Insight only to get turned off by how cartoony it initially looks.

“Goto implementation” for constructors never works. It works for destructors and all other methods of a class — go figure.

Custom regular expressions. SI’s syntax is pretty good but it’s its own custom flavor. For instance: it doesn’t let you do multiline regex — this can occasionally be a pain when trying to do multi-line search and replace operations.

Cut and copy from SI .txt files to Microsoft products strip line feeds. I’ve got no idea why, but most ms programs think blocks of text pasted from Source Insight .txt files dont have proper line feeds. If I resave the .txt file as a .cpp it always works.

No extended features. Source Insight is just an editor and nothing else. Sure there’s a very small macro language, and sure you can launch command line programs and parse their results. But there are no source control plugins, no package managers, no debuggers, no compilers, no maven like task managers, etc. This is all good, and all bad. It really would be nice if it supported plugins ( and if some existed . If it did, it’d be nice — unlike Eclipse and NetBeans — to initialize them after load, so that the startup / access sequence stays fast.

No built in refactoring. Eclipse and Netbeans offer some pretty impressive auto-refactoring abilities that would be great to see in more products including Source Insight.

Windows only. Sigh. I’ve already been doing some development on Ubuntu, I’d like to work on a Mac. What will I do?

Conclusions

Can’t live without it, and, unfortunately, sometimes can’t live with it. I think for C and C++ I’m stuck. It’s a great product with features I don’t want to give up and that no one else has. But, unless a new round of fixes and language expansions rolls in, for everything else: I’ve got to move on.

I wish so much more for this great editor and wish others would see it and adopt it’s features. However, I’m pretty sure there’s just one person who maintains source insight these days — and the company doesn’t charge much: I paid maybe a hundred or so US dollars a few years ago for version 3 and get free updates once a year or so.  It’s still the same version today but the price is now a little over 200 dollars — at any rate I suspect these days it’s just someone’s side job or hobby, and it could possibly be facing death in obscurity.

Maybe someday, if it’s indeed on that path, the author(s) could open source the code and it could live a new fresh life again. Hopefully inspiring others with its goodness along the way.

Don’t go there. It’s the dark side.

Turn towards something different. Call it MVC, call it narrow encapsulation, call it one of the most important design choices you can make in your game’s architecture: get movement out of your actor class, remove behavior of all kinds.

Your object-orientated instincts — especially if, for some reason that I have yet to put my finger on, your background is in C++ — might tell you: if an object can take an action, then that action should be a method on the object in question.

Take whatever book you read that in and burn it.

Lemons are objects; making lemonade is not an object.

Before I get into this too deeply, I should explain: by object here I don’t mean class. Conceptually, by object here I mean: it has a real world physical analog. It’s an object in the sense that your non-programming friends would understand.

Behavior may be a class, but is not an object.

Take the questionable lemon. You can’t get away from this new law of the land by simply moving your “squeeze” function to the lemonade stand. Try it and the police are already at your door.

The lemonade stand is an object. The person making the lemonade? An object. The lemonade itself? You guessed it: an object.

Making lemonade? Not an object.

So what should an object contain then anyway if not the methods that give it character and life? Honestly: I’d suggest radicalism. Overcorrect, rather than under correct. Save yourself lengthy legal arguments. Head back towards C and Plain-Old-Data structures.

To be on the safe side: the essential properties and attributes of the conceptual object should go in your object class — and nothing else. I’m not arguing for truly pure POD structures — so I’m not saying only your essential member variables — but rather those variables and the bare minimum number of methods necessary to expose those to the rest of your game.

As an example from a basketball game. Your actor might have the variables “height off the floor” and “current speed” and it might use those to expose the properties: “isRunning()” and “isJumping()”. But, just because you can put the “jump()” method in your Actor class doesn’t mean you should.

In order for your code to live a long and healthy life — you really want to wind up in a situation where a single code base could possibly be reused multiple times. If your actor, for instance, gets a “shootHoop()” method — you are not going to want to reuse that actor class for a hockey game. Now, if perhaps you aren’t interested in that level of reusability, consider the following much more likely case.

You are two years into the development of a new first person shooter and suddenly your designer says to you: I really need the player to drive a car in this part of the game. If the only tool available to you is to add “steer()”, “accelerate()”, and “brake()” to your human actor object class — I can guarantee you are going to have some long sleepless nights ahead of you. In this case, your actor class is probably already several thousand lines long, and to add even simplistic driving, its going to become several thousands more. Even if you can shunt most of the code of into a car class, your main human actor will be inextricably bound up to that car, and the number of dependencies between states within these two classes will start to give you nightmares once you can grab some shuteye.

As a programmer you might feel inclined to blame design for not letting you know 2 years ago you might have car driving as a one off in your game — but the reality is: that’s just game development. Your code has to be able to cope with radically shifting needs. Separating behavior and the objects behaviors operate upon will help get you to that point.

“Object-oriented” does mean the language orients — focuses — you on using objects… just don’t let it imprison you there.

I’m porting my python dungeon crawler over to java, and am trying to get it up and running one small piece at a time. For the first time I’m trying out true unit tests; trying to get each piece debugged before setting the whole thing going as one.

I’m currently faced with a deceptively simple choice: should a “Room” class contain a list of pointers to “Actor” objects?

If you feel the answer is: yes, of course Rooms should contain Actors, you probably consider yourself a McCoy programmer: a programmer who favors simple, easy to understand code, that executes quickly. If you say: good god no, you probably consider yourself a good engineer, a person who creates robust code for the long haul, a purely Hatfield programmer.

Behind their back McCoy programmers get called hackers, spaghetti programmers, baby killers; Hatfield programmers get called language lawyers, code obfuscators, Bush administration supporters.Even today the Hatfields and the McCoys don’t get along.

If you are unlucky: you will have both ardent Hatfields and ardent McCoys on your team, both sides hell bound to have their way. Debates over simple choices will rage for weeks, no code will actually get written, your game will get cancelled, and you’ll be forced to live out your days penniless.

If you’re really unlucky you’ll have someone who professes to be a Hatfield but codes like a McCoy. This person will know just what to do, will spend two weeks coding something “abstract” and “decoupled” that’s 6000 lines long, distributed across eight object classes, and uses string compares to look up actors. Your game will ship and become wildly successful. They will get a promotion, while you will have to spend the rest of your career maintaining something so fragile that it breaks every time a stray neutrino passes near.

Fundamentally, there is no right answer to the question I’ve posed. Software is pliable, and it allows you to make whatever choices you want. When “mu” choices come up I generally just take my best most educated guess and move on, correcting bad choices later on.

I justify this with a personal tenet that programmers need to get code into customers’ hands as quickly as reasonably possible. ( The quality level of “reasonable” and the speed of “quick” being up to endless debate on a case by case basis ).

My python code therefore is currently McCoy like — it has bi-directional pointers, Rooms hold Actors, Actors track their parent room. Unfortunately, both my Actor and my Room classes have become top heavy: if I port one, I have to port the other.

I am at a cross-roads then, I can:

• port both together
• create abstract base classes for each to lighten the load, then port each in turn.
• separate the two from each other entirely.

The land of databases sheds some light: If I were to construct these as tables, I never would have been able to have had one complex class contain lists of another complex class — I’d have to an Actor table, a Room table, and a third, ActorsInRooms, table.

Taking that metaphor forward: it’s easily possible to create the ActorsInRooms table up front as small and as flat as the list of the Rooms itself can be. For a static per level set of rooms: a simple level load time allocated array — indexed by room id — will be just as quick (I’m throwing cache to the wind here) and just as small as a direct in Room list of actors.

Later, if the Rooms need to get Items, Lights, Fixtures, etc. We have a nice simple model that allows for fast. compact, lookup when needed without bogging down the Room object model.

The downside may be that, if Rooms become dynamic, that list may have to become a hash at some point — but, down that route, the Rooms themselves will need to go in a hash, and so perhaps, it will be possible to create a shared central lookup.

At any rate: here’s a rule of thumb I advocate that isn’t repeated enough in code design books, classes, discussions, etc. Keep your classes SMALL. Try to keep per class responsibilities down. If classes start to get big, side step that increase by introducing simple relationship objects that can help express connections between objects.

Most importantly, however, revise and streamline your class design as you go. Don’t worry about abstract choices too much. Instead, focus on getting reasonable code in your customers’ hands quickly. Later, as you learn about the issues your code needs to handle, take the time to make your code better.

1. … do some stuff … run python … do some more stuff … run more python …

Simultaneous execution: run with multiple threads, launching ( and perhaps reusing ) a second thread whenever you want to run one of the high level PyRun*() functions

1. … do some stuff … do some more stuff …
2. … run python …. run more python …

The first method means that your python script will block your game’s processing loop; the second method means you have to synchronize access to any data shared between your game and python.

If you are only running truly short scripts, the first one might work — though you will definitely want some way to abort scripts that enter an infinite loop. ( the code in this post could be adapted to do just that )

For the long haul, the second one will work must better, but it will definitely take more thought and more work up front. For quick and dirty integration, especially if you are in a situation where you are embedding scripting in order to support debugging and prototyping and don’t intend to ship with Python as part of your game that extra work may be a burden.

Ideally, there would be an alternative embedding where you could run python for a small slice of time during each single frame.

Essentially, your game loop might then look something like this:

• main_game_loop()
• process_input()
• run_game_updates()
• run_python_for_a_limited_time()
• render()

While this does have some of the same downsides as the pure simultaneous model — namely that a single C/++ based object might appear to have several different states over the course of a single loop of python processing — it wouldn’t require that the actual reading to and writing from C/++ objects be thread safe. The fact that python and the rest of your game run at completely times ensures that object access isn’t occurring simultaneously.

There appear to be two basic ways to accomplish this time-sliced processing mode.

1. Use the standard high level PyRun() commands, interrupting processing at a “safe time” once the desired slice of time has elapsed.
2. Eschew the higher level PyRun() commands, executing commands from the script one at a time until the slice has expired.

So far I’ve only explored the first method, and while it runs, it doesn’t feel particularly clean. The rest of this post will be devoted to documenting — for good or for ill — how it works. At some future point I will probably try to figure out how to accomplish the second method, perhaps by looking more closely at how python debuggers work.

The GIL

First thing first is to understand a little bit about the way the python interpreter works — I’m not an expert by any stretch of imagination — so feel free to question / correct me if you think I’ve got things wrong.

Basically, regardless of how many threads of Python processing you have going there is, conceptually, one central python execution engine. This central engine is protected by a single global synchronized object — only one thread can own the object at a time, only the thread that owns the object will run its python instructions through the engine.

The object in the docs is referred to as the GIL — the global interpreter lock — and in Python2.5 it’s represented by the static variable “interpreter_lock” in ceval.c. The Python/C API allows a thread to request a lock on the GIL — the request blocks that thread until the lock succeeds — and unlock the GIL, which allows other threads who have requested the GIL to get the lock so that they can run.

The GIL works differently than a typical critical section or mutex. Basically, every one hundred instructions or so, at the same time that the currently running thread normally checks for interrupts ( ctrl-c ) and external i/o signals, the running thread releases the GIL, and then immediately tries to reacquire it. If there are any other threads who have been waiting on the GIL, they will get the lock, and the previously current thread will be suspended. ( Python also releases and reacquires the GIL at other times: mainly (only?) during reading new python from files, including from the stdin. )

Reading through the docs trying to understand exactly how the GIL and the functions that manipulate it work can be a bit confusing. The API for manipulating the GIL is named in a way that focuses on extending python — your app being called back by python — rather than embedding — you calling into python.

From the extending point of view the overall process for two threads runs something like this:

• Run a Python file

• thread A requests a lock on the GIL
• thread A does stuff, perhaps executing a function in a C extension
• the extension does stuff, returns
• 100 instructions later thread A unlocks GIL and immediately request a lock again
• thread B, who was waiting, gets the GIL first
• thread B does stuff, perhaps executing a function in a C extension
• 100 instructions later thread B releases the GIL and immediately requests another lock
• thread A, who was waiting, gets the GIL first
• …
• the threads reach the end of their python instructions and exit.

The API for manipulating the GIL therefore is centered around the concept that the extension may take some significant amount of time, and, if there are multiple threads of python code, that blocking for too long would be bad. The pseudo code in the docs therefore looks something like this:

• Python:
• thread A requests the GIL
• thread A executes a C extension function
• C extension:
• saves the “thread state” of thread A
• unlocks the GIL - thread B can begin processing python code
• extension does blocking stuff
• lock the GIL again - will block until it can acquire the GIL from thread B
• restores the thread state of thread A
• the extension returns to python
• 100 instructions later thread A releases the GIL again
• …

Thread State Oddities

The “thread state” referred to above, is an internal python record keeping object — it stores information on the actual OS thread ( on my system the Window’s thread handle ) but more importantly, stores pointers to all of the information that Python needs to process code.

Python’s execution engine can’t run without a valid thread state object.

In two strange quirks of the API, Python will only allow you to set the thread state of the engine to a thread state that originated on the current thread, and the API will only allow you to have one thread state per thread. This means that there must exist a one to one mapping between the real operating system thread and the python thread state, and only the OS thread that owns the python thread state can manipulate its python thread state.

While this seems on the surface logical, it’s actually quite odd. Python knows those things well enough to be able to check them — and if you don’t play by the rules Python complains loudly — so why then does it even allow you to, really require you to, manipulate them? Python’s engine itself could just select the right thread state any time someone successfully acquires a lock. Lockers that don’t yet have a thread state would have it swapped in when they first create a thread state, deletion of a thread state would only ever delete the current one.

At any rate, this has implications for the timeslicing, because it limits what API functions you can legally call from where.

Time slicing

Here’s what I’ve found works, the following code is split up two threads — the main thread (MT) and the time-sliced thread (TT).

The main thread handles three functions: start(), process(), stop(), while the time-sliced thread has only a single run() function.

In this example start() takes a filename that the time-sliced thread will have python process, in little per frame chunks, until finished.

Wherever a request to lock the GIL occurs I’ve put a <
Wherever the GIL gets unlocked a corresponding >
Wherever a thread state is swapped in a [
Wherever it’s swapped out a ]

Again, the thread state needs to be forcibly swapped in before you run any python code from the current thread.

MT: start()

• initialize python embedding
• initialize python thread package
• create TT; force it to start life suspended.

MT: process()

• resume TT
• wait for the desired time slice
• < suspend TT>

MT: stop()

• <[ send an exit interrupt to TT, then resume TT ]>
• wait for TT to exit
• close TT thread handle

TT: run()

• < create a thread state>
• load the requested file
• <[ use Python to print out the results of the file load ]>
• <[ PyRun() the file ]>
• close the file
• < delete the thread state>

In process() the main point is that the gets GIL locked before the thread is suspended. This ensures that the thread is at safe spot in its execution of python code — a place where it expects that it might be swapped out.To handle the wait I’m using Window’s WaitForSingleObject().
While it’s not the most accurate timer, it does the main thread to sit idle for a short amount of time.

Ideally, Python’s lock object would be available for Wait() on, but it’s not exposed for direct use by embedding apps. You can only access it through the low level PyEval_Acquire/ReleaseLock() and the higher level functions that wrap those calls.

The only real alternative therefore is to WaitForSingleObject on your processing thread, and then, after the wait has finished, request a lock on the GIL, which block your thread until python is at a “good enough” stopping point ( for instance: not in a callback into your own app ) where you can then suspend the thread entirely until the next frame.

I suppose, actually, another, perhaps even better alternative, would be to remove the wait() altogether, and just sit in a tight loop, requesting the gil, checking the elapsed time, estimating when is a good time to exit the tight loop. You could even track the time it took to execute the last 100 statements, and thus guess at when the next round of processing will drive the time sliced thread over its time limit.

MT: process()

• resume TT
• while (TT is still valid)
• lock the gil (<)
• check time
• if estimated time is more than the desired time:
• suspend TT, unlock the gil (>)
• if its safe to run some more:
• unlock the gil (>) and continue the loop

Sample Code

At any rate:

Here’s the real deal: TimeSlicedPython.zip
Hope it’s useful to you and that it gives you some new insights into how Python works under the hood.