Showing obvious concrete examples of data corruption due to unsafe threaded code isn’t actually as easy at it sounds. First of all, even with a GIL, developers can write unsafe threaded code. So we need to focus only on the safety problems raised by removing the GIL. To demonstrate what I mean, I will try to create some race conditions and show you the unexpected results you might get. Again, before you go crazy on the comments, remember that threaded code is indeterministic and the code below might potentially work on your machine and that’s exactly why it is hard to demonstrate. Race conditions depend on many things, but in this case I will focus on race conditions affecting basic data structures since it might be the most surprising.

Example:

@array, threads = [], []
4.times do
  threads << Thread.new { (1..100_000).each {|n| @array << n} }
end
threads.each{|t| t.join }
puts @array.size

In the above example, I’m creating an instance variable of Array type and I start 4 threads. Each of these threads adds 100,000 items to the array. We then wait for all the threads to be done and check the size of the array.

If you run this code in C Ruby the end result will be as expected:

400000

Now if you switch to JRuby you might be surprised by the output. If you are lucky you will see the following:

ConcurrencyError: Detected invalid array contents due to unsynchronized modifications with concurrent users
        << at org/jruby/RubyArray.java:1147
  __file__ at demo.rb:3
      each at org/jruby/RubyRange.java:407
  __file__ at demo.rb:3
      call at org/jruby/RubyProc.java:274
      call at org/jruby/RubyProc.java:233

This is actually a good thing. JRuby detects that you are unsafely modifying an instance variable across threads and that data corruption will occur. However, the exception doesn’t always get raised and you will potentially see results such as:

335467
342397
341080

This is a sign that the data was corrupted but that JRuby didn’t catch the unsynchronized modification. On the other hand MacRuby and Rubinius 2 (dev) won’t raise any exceptions and will just corrupt the data, outputting something like:

294278
285755
280704
279865

In other words, if not manually synchronized, shared data can easily be corrupted. You might have two threads modifying the value of the same variable and one of the two threads will step on top of the other leaving you with a race condition. You only need 2 threads accessing the same instance variable at the same time to get a race condition. My example uses more threads and more mutations to make the problem more obvious. Note that TDD wouldn’t catch such an issue and even extensive testing will provide very little guarantee that your code is thread safe.

So what? Thread safety isn’t a new problem.

That’s absolutely correct, ask any decent Java developer out there, he/she will tell how locks are used to “easily” synchronize objects to make your code thread safe. They might also mention the deadlocks and other issues related to that, but that’s a different story. One might also argue that when you write web apps, there is very little shared data and the chances of corrupting data across concurrent requests is very small since most of the data is kept in a shared data store outside of the process.

All these arguments are absolutely valid, the challenge is that you have a large community and a large amount of code out there that expects a certain behavior. And removing the GIL does change this behavior. It might not be a big deal for you because you know how to deal with thread safety, but it might be a big deal for others and C Ruby is by far the most used Ruby implementation. It’s basically like saying that automatic cars shouldn’t be made and sold, and everybody has to switch to stick shifts. They have better gas mileage, I personally enjoy driving then and they are cheaper to build. Removing the GIL is a bit like that. There is a cost associated with this decision and while this cost isn’t insane, the people in charge prefer to not pay it.

Screw that, I’ll switch to Node.js

I heard a lot of people telling me they were looking into using Node.js because it has a better design and no GIL. While I like Node.js and if I were to implement a chat room or an app keeping connections for a long time, I would certainly compare it closely to EventMachine, I also think that this argument related to the GIL is absurd. First, you have other Ruby implementations which don’t have a GIL and are really stable (i.e: JRuby) but then Node basically works the same as Ruby with a GIL. Yes, Node is evented and single threaded but when you think about it, it behaves the same as Ruby 1.9 with its GIL. Many requests come in and they are handled one after the other and because IO requests are non-blocking, multiple requests can be processed concurrently but not in parallel. Well folks, that’s exactly how C Ruby works too, and unlike popular believe, most if not all the popular libraries making IO requests are non blocking (when using 1.9). So, next time you try to justify you wanting to toy with Node, please don’t use the GIL argument.

What should I do?

As always, evaluate your needs and see what makes sense for your project. Start by making sure you are using Ruby 1.9 and your code makes good use of threading. Then look at your app and how it behaves, is it CPU-bound or IO-bound. Most web apps out there are IO-bound (waiting for the DB, redis or API calls), and when doing an IO call, Ruby’s GIL is released allowing another thread to do its work. In that case, not having a GIL in your Ruby implementation won’t help you. However, if your app is CPU-bound, then switching to JRuby or Rubinius might be beneficial. However, don’t assume anything until you proved it and remember that making such a change will more than likely require some architectural redesign, especially if using JRuby.  But, hey, it might totally be worth it as many proved it in the past.

I hope I was able to clarify things a bit further. If you wish to dig further, I would highly recommend you read the many discussions the Python community had in the last few years.

The GIL was probably even more of a hot topic now that Rubinius is about the join JRuby and MacRuby in the realm of GIL-less Ruby implementations.

During my RubyConf talk (slides here), I tried to explain how C Ruby works and why some decisions like having a GIL were made and why the Ruby core team isn’t planning on removing this GIL anytime soon. The GIL is something a lot of Rubyists love to hate, but a lot of people don’t seem to question why it’s here and why Matz doesn’t want to remove it. Defending the C Ruby decision isn’t quite easy for me since I spend my free time working on an alternative Ruby implementation which doesn’t use a GIL (MacRuby). However, I think it’s important that people understand why the MRI team (C Ruby team) and some Pythonistas feels so strongly about the GIL.

What is the GIL?

Here is a quote from the Python wiki:

In CPython, the global interpreter lock, or GIL, is a mutex that prevents multiple native threads from executing Python bytecodes at once. This lock is necessary mainly because CPython’s memory management is not thread-safe. (However, since the GIL exists, other features have grown to depend on the guarantees that it enforces.) [...] The GIL is controversial because it prevents multithreaded CPython programs from taking full advantage of multiprocessor systems in certain situations. Note that potentially blocking or long-running operations, such as I/O, image processing, and NumPy number crunching, happen outside the GIL. Therefore it is only in multithreaded programs that spend a lot of time inside the GIL, interpreting CPython bytecode, that the GIL becomes a bottleneck.

The same basically applies to C Ruby. To illustrate the quote above, here is a diagram representing two threads being executed by C Ruby:

Such a scheduling isn’t a problem at all when you only have 1 cpu, since a cpu can only execute a piece of code at a time and context switching happens all the time to allow the machine to run multiple processes/threads in parallel. The problem is when you have more than 1 CPU because in that case, if you were to only run 1 Ruby process, then you would most of the time only use 1 cpu at a time. If you are running on a 8 cpu box, that’s not cool at all! A lot of people stop at this explanation and imagine that their server can only handle one request at a time and they they rush to sign Greenpeace petitions asking Matz to make Ruby greener by optimizing Ruby and saving CPU cycles. Well, the reality is slightly different, I’ll get back to that in a minute. Before I explain “ways to achieve true concurrency with CRuby, let me explain why C Ruby uses a GIL and why each implementation has to make an important choice and in this case both CPython and C Ruby chose to keep their GIL.

Why a GIL in the first place?

• It makes developer’s lives easier (it’s harder to corrupt data)
• It avoids race conditions within C extensions
• It makes C extensions development easier (no write barriers..)
• Most of the C libraries which are wrapped are not thread safe
• Parts of Ruby’s implementation aren’t threadsafe (Hash for instance)

Should C Ruby remove its GIL?

• No: it potentially makes Ruby code unsafe(r)
• No: it would break existing C extensions
• No: it would make writing C extensions harder
• No: it’s a lot of work to change make C Ruby threadsafe
• No: Ruby is fast enough in most cases
• No: Memory optimization and GC is more important to tackle first
• No: C Ruby code would run slower
• Yes: we really need better/real concurrency
• Yes: Rubber boots analogy (Gustavo Niemeyer)

How can true concurrency be achieved using CRuby?

Finally, when developing web applications, each thread spend quite a lot of time in IOs which, as mentioned above won’t block the thread scheduler. So if you receive two quasi-concurrent requests you might not even be affected by the GIL as illustrated in this diagram from Yehuda Katz:

This is a simplified diagram but you can see that a good chunk of the request life cycle in a Ruby app doesn’t require the Ruby thread to be active (CPU Idle blocks) and therefore these 2 requests would be processed almost concurrently.

MacRuby is so awesome that Apple is even using it in its upcoming OS. The only problem is that Apple apparently decided to not share MacRuby with other OS X developers and put MacRuby in the OS private frameworks. While this doesn’t affect the project itself, it does affect OS X developers like myself who can’t link to Lion‘s private MacRuby framework and are forced to embed MacRuby with their applications.

That’s why I have opened a ticket on Apple radar system to ask that MacRuby be made a public framework.

If you also want Apple to make this change, please take a minute and let them know.

C/Objective-C code can be called directly from MacRuby. However the Obj-C code you would like to use might be using some ANSI C symbols that are non-object-oriented items such as constants, enumerations, structures, and functions. To make these items available to our MacRuby code, you need to generate a BridgeSupport file as explained in this section of my book.

In our case, we were working on the framework and I didn’t feel like manually having to regenerate the BridgeSupport file every single time I would compile our code. So instead I added a new build phase in our target.

Adding a new step to our build

And I added the following script to run at the end of the build:


# This step generated the bridgesupport file for the framework
PATH="$PATH:/usr/local/bin"
mkdir -p $TARGET_BUILD_DIR/$PROJECT_NAME.framework/Resources/BridgeSupport/
gen_bridge_metadata --64-bit -f $TARGET_BUILD_DIR/$PROJECT_NAME.framework/ -o $TARGET_BUILD_DIR/$PROJECT_NAME.framework/Resources/BridgeSupport/$PROJECT_NAME.bridgesupport


The script just executes the steps required to add the BridgeSupport file to your framework. I can now rebuild my framework without having to worry about BridgeSupport.


If you already purchased  an electronic copy (thank you!), go to your product page and download an update. Note that if you are on an iPhone or iPad and you click on the .epub link, the file will automatically load in iBooks, same thing if you have the kindle app installed and you are clicking on the .mobi file.

If you haven’t purchased an electronic version yet, you can still read the book in HTML format here. If you choose to do so, please still think about leaving a review on the O’Reilly site to show your support to myself and to my publisher.

What’s new in this update?

App built in chapter 2

1. I refactored the introduction to the book, you know have a new Chapter 2 which introduces you to GUI app development and lets you build a full app right away to give you an idea of what is available.
2. Chapter 3 covers more advanced concepts and was updated to reflect changes made on trunk.
3. The chapter on Core Data is now almost done, I will soon push an update with the end of the chapter, but between the chapter content and the example app, you should be good to go today.
4. GitHub repo with the code used in the book. (work in progress, I need to move more code there)
5. The book is now divided in two parts, one more theoretical and more practical. Even if part 2 isn’t written yet, the table of contents shows some of the examples I will cover. I hope to have some of these chapters written in a few weeks.
6. Lots of small fixes and updates thanks to the readers comments and to my editor.

App built in the Core Data chapter

Finally if you are interested in pre-ordering the book, Amazon runs a great deal on the book:

Thank you for your support!

I started thinking about working on “MacRuby: The Definitive Guide” last year when I realized that the project had a great future but there was a serious lack of documentation. With the support of the MacRuby team, I worked on a table of contents and a pitch. The next step was to decide what we wanted to do with the book.

I know a lot of technical book authors and most of them will tell you the same thing: if you think that you are going to make money writing a book, you are wrong. Even if your book sells well, because of the time invested in writing the book, you are probably better off doing consulting work and charging by the hour.

So since day one, I knew that this project would not make me rich. The goal was to share knowledge not to reimburse my mortgage or save California from bankruptcy. While publishing a web book is great, distribution is quite limited, especially if you try to reach people outside of your network. That’s why I decided to start talking to a few publishers. Most publishers I talked to were interested in working on the book, however they were not really keen on publishing a Creative Commons Attribution-Noncommercial-No Derivative licensed book.

Let me explain why I think releasing technical books under a CC license is important. As you might know (or have figured out by now), I am not a native English speaker. I actually learned my first English words thanks to the computer my dad had at home. The problem when you don’t live in an English speaking country and you want to learn about the cutting edge technology is that you have to understand English.  Thanks to the Internet, learning and practicing English is now much easier that it used to be. However, if you want to have access to books, most of the time you have to wait until someone translates the book and publishes it in your country or you have to manage to get an English version delivered to your country. This is often a pain because of national credit card limitations, international delivery restrictions etc… If you manage to find a way to get a copy, the book ends up costing a lot of money.

What does that mean in practice? Most of the technical books are first available in the English speaking western world, then slowly translated and/or distributed around the world. By the time you get a legal copy in Bolivia, Algeria or Vietnam, a new edition is probably out in the US probably because the technology evolved. Maybe that explains some of the book piracy worldwide?

Think about it for a minute: knowledge is power and time is money. And what do we do? We delay knowledge distribution. This is why I am a big fan of the Khan Academy and its awesome free online courses.

Turns out O’Reilly shares my vision and has already published a lot of books under various open licenses: http://oreilly.com/openbook/ I was also interested in publishing the content of my book ASAP so people could access it right away even though there would be lots of typos and missing content. This is also something O’Reilly has already done with the CouchDB and the Scala books.

Talking with Jan Lehnardt about his experience working with O’Reilly on the ‘CouchDB: The definitive guide’ book, I realized that we seem to have some shared interests. I contacted Jan’s editor and we decided to start working on the MacRuby book. The book will be available later on in all the usual commercial formats and I hope people will show their support so O’Reilly will be encouraged in their choice to continue publishing CC licensed book. At the end of the day, purchasing a CC licensed book helps supporting the authors, the publishers but also all the people who can’t have access to the latest technical books.

Finally, working on a book is not an easy thing, especially when you have to write it in a language that’s not yours. But I have to say that the community support has been amazing. Even John Gruber sent a fireball my way. And since the announcement was made, I have received a lot of comments, tweets, emails etc… It is very encouraging and it gives me the motivation needed to work on the book after a long work day.

In some instances things might look quite weird to someone new to Cocoa in some cases, things seem almost too easy. Here is an example implementing a undo/redo functionality using Foundations’ NSUndoManager.

framework 'Foundation'
class Player
  attr_accessor :x, :y
 
  def initialize
    @x = @y = 0
  end
 
  def undo_manager
    @manager ||= NSUndoManager.alloc.init
  end
 
  def left
    undo_manager.prepareWithInvocationTarget(self).right
    @x -= 1
  end
 
  def right
    undo_manager.prepareWithInvocationTarget(self).left
    @x += 1
  end
end

Which you can use as such:

 
>> lara = Player.new
=> <Player:0x200267c80 @y=0 @x=0>
>> lara.undo_manager.canUndo
=> false # normal since we did not do anything yet
>> lara.left
=> -1
>> lara.x # -1
=> -1
>> lara.undo_manager.canUndo
=> true # now we can undo, so let's try
>> lara.undo_manager.undo # undo back to initial position
=> #<NSUndoManager:0x200257560>
>> lara.x
=> 0
>> lara.undo_manager.canUndo
=> false # we can't anymore which makes sense 
>> lara.undo_manager.canRedo
=> true # however we can redo what we just undone
>> lara.undo_manager.redo # redo to before we called undo
=> #<NSUndoManager:0x200257560>
>> lara.x
=> -1

The above example was tested in macirb but as you can see, actions can be undone and redone very very easily. This is just a quick preview of what you can do using Ruby + Cocoa and hopefully it will give you some cool ideas to implement.

I’ll let you check on the TODO list to see what was done in 0.5 and what is in the plan for 0.6.

However, there is one feature in 0.6 that I know lots of you will just love! The good news is that Laurent already committed a very early version of his work so I figured, I should share the good news with you:

Introducing MacRuby’s debugger!

If you were expecting to read: “a Cylon detector!”, keep on reading.

Again, this feature is in really early development since it’s scheduled for 0.6 and 0.5 final is not out yet. But if you install MacRuby using the nightly builds or build from trunk, you can already play with the debugger.

Let me give you a really quick tour of the debugger.

Let’s imagine that we were given the task to debug the cylon detector written by Gaius Baltar which looks like that:

characters = %w{Adama Apollo Baltar Roslin StarBuck Six}
 
def cylon?(character)
  false
end
 
characters.each do |character|
  if cylon?(character)
    puts "#{character} is a Cylon!"
  else
    puts "#{character} is not a cylon."
  end
end

Here is what happens when I execute the script:

$ macruby cylon_detector.rb 
Adama is not a cylon.
Apollo is not a cylon.
Baltar is not a cylon.
Roslin is not a cylon.
StarBuck is not a cylon.
Six is not a cylon.

The only problem is that we all know that Six is a Cylon, the detector isn’t working right so let’s debug it:

$ macrubyd cylon_detector.rb
Starting program.
cylon_detector.rb:1> b cylon_detector.rb:8 if character == 'Six'
Added breakpoint 1.
cylon_detector.rb:1> c
Adama is not a cylon.
Apollo is not a cylon.
Baltar is not a cylon.
Roslin is not a cylon.
StarBuck is not a cylon.
cylon_detector.rb:8> p cylon?(character)
=> false
cylon_detector.rb:8> p "This detector is broken!"
=> "This detector is broken!"
cylon_detector.rb:8> p def cylon?(character); character == 'Six'; end
=> nil
cylon_detector.rb:8> p cylon?(character)
=> true
cylon_detector.rb:8> p cylon?('Matt')
=> false
cylon_detector.rb:8> c
Six is a Cylon!
Program exited.

The first thing we do is to add a conditional breakpoint:

b cylon_detector.rb:8 if character == 'Six'

Basically, the debugger will add a breakpoint at line 8 which will only be active when the value of ‘character’ is equal to ‘Six’.
Now that the breakpoint added, we can continue the program execution and just wait until we reach the defined condition.

cylon_detector.rb:1> c

Once we reach the breakpoint, we evaluate the result of “cylon?(character)” by using the p command. We see that the result is “false” when we know for sure that it should be true since the value of the character variable is ‘Six’ and she is a cylon. At this point, you might have guessed that somewhat acted as a cylon agent and I pretended to fix the problem by overwriting the “cylon?” method:

cylon_detector.rb:8> p def cylon?(character); character == 'Six'; end

Now that the method is overwritten, I can check that Six is recognized as being a cylon:

cylon_detector.rb:8> p cylon?(character)
=> true

and also check that I am not detected a cylon:

cylon_detector.rb:8> p cylon?('Matt')
=> false

I can now continue the execution of the program and see that Six is detected as a Cylon!

Of course this is just a very early version of the debugger and we will see lots of improvement in the next few weeks. Who knows someone might even create a GUI for the debugger and/or a Xcode integration.

Anyway, the point being that MacRuby developers should expect a lot of awesome stuff coming up their way soon. (also be careful about the skin jobs around you, cylon detectors can’t be trusted!)

A few weeks back, I showed how to control iChat with MacRuby. This time I’m going to show you how to control iTunes.

Here is a small script that I wrote to wake me up in music every morning.

#!/usr/local/bin/macruby
framework 'Foundation'
framework 'ScriptingBridge'
 
itunes = SBApplication.applicationWithBundleIdentifier("com.apple.itunes")
load_bridge_support_file 'iTunes.bridgesupport'
itunes.run
 
class SBElementArray
  def [](value)
    self.objectWithName(value)
  end
end
 
itunes.stop
playlist = itunes.sources["Library"].userPlaylists["morning"]
playlist.playOnce(false) if playlist

The idea is that I have a Mac Mini streaming music through speakers connected to an AirportExpress in my bedroom.

Let’s go through the script quickly.

We start by loading two frameworks, Foundation and ScriptingBridge.
Now that we have ScriptingBridge loaded, we can control iTunes. To do that, we use:
SBApplication.applicationWithBundleIdentifier(“com.apple.itunes”)
We then load a bridgesupport file that contains the enumerated constants from the iTunes scriptable dictionary.

We make sure iTunes is running by calling #run on the application object.

Before using iTune scriptable interface, we are making the API a bit nicer, it’s totally unnecessary but it makes our code look better.

itunes.sources returns an instance of SBElementArray which is not really an array nor a hash.

The rest of the code is pretty simple, we find the library, find the playlist called ‘morning’ and play it if found.

So you might wonder two things:

• What is the iTunes.bridgesupport file?
• How do you know what methods are available to control iTunes?

bridgesupport file

The bridgesupport file is important since it defines the required constants.
Apple provides a metadata generator called gen_bridge_metadata which generates a bridgesupport file.

Here is what the documentation says:

$ man gen_bridge_metadata

NAME
gen_bridge_metadata -- Objective-C Bridges Metadata Generator
 
SYNOPSIS
gen_bridge_metadata [options...] headers...
 
DESCRIPTION
gen_bridge_metadata is a tool that generates bridging metadata information for a given framework or set of head-
ers. The Objective-C bridges supported in Mac OS X, such as RubyCocoa (Ruby) and PyObjC (Python), read this
information at runtime.
 
Metadata files describe the parts of an Objective-C framework that the bridges cannot automatically handle. These
are primarily the ANSI C elements of the framework -- functions, constants, enumerations, and so on -- but also
include special cases such as functions or methods that accept pointer-like arguments. These special cases must
be manually specified in separate files called exceptions. The gen_bridge_metadata tool can then read in the
exceptions file when it generates the framework metadata.
 
The file extension used for metadata files should be .bridgesupport.
 
Certain elements, such as inline functions, cannot be described in the metadata files. It is therefore required
to generate a dynamic library in order to make the bridges use them. The gen_bridge_metadata tool can take care
of that for you.
 
The file extension for the dynamic libraries should be .dylib.
 
You should install metadata files in one of three filesystem locations. For example, for a framework named
MyFramework that is installed as /Library/Frameworks/MyFramework.framework, you can install the
MyFramework.bridgesupport and MyFramework.dylib files in one of the following possible locations, in order of
priority:
 
o   /Library/Frameworks/MyFramework/Resources/BridgeSupport
 
o   /Library/BridgeSupport
 
o   ~/Library/BridgeSupport

The problem is that we don’t have a framework or header file to generate a bridgesupport file for.
So, what we need a header file for iTunes, turns out we have a tool to do that:

$ sdef /Applications/iTunes.app | sdp -fh --basename iTunes

I won’t go in the details of what sdef and sdp do, just check their manual page.
Running the command above will create a iTunes.h which we can use to create a bridgesupport file.
Here is the generated header file: http://gist.github.com/279657

Now, let’s create a bidgesupport file:

$ gen_bridge_metadata -c '-I.' iTunes.h > iTunes.bridgesupport

An that’s how we get the bridgesupport file. (see file: http://gist.github.com/279698)

iTunes Documentation

The easiest way to understand what’s available to you is to open iTunes’ dictionary in the AppleScript Editor.

Otherwise you can study the iTunes.h file.

I wrote a very dumb parser to give you an idea of the methods and properties available when controlling iTunes via ScriptingBridge, here is the  output:

Class: iTunesPrintSettings
Properties:
copies (the number of copies of a document to be printed)
collating (Should printed copies be collated?)
startingPage (the first page of the document to be printed)
endingPage (the last page of the document to be printed)
pagesAcross (number of logical pages laid across a physical page)
pagesDown (number of logical pages laid out down a physical page)
errorHandling (how errors are handled)
requestedPrintTime (the time at which the desktop printer should print the document)
printerFeatures (printer specific options)
faxNumber (for fax number)
targetPrinter (for target printer)
 
Method: printPrintDialog:(BOOL)printDialog withProperties:(iTunesPrintSettings *)withProperties kind:(iTunesEKnd)kind theme:(NSString *)theme
Returned: void
Print the specified object(s)
----
Method: close
Returned: void
Close an object
----
Method: delete
Returned: void
Delete an element from an object
----
Method: duplicateTo:(SBObject *)to
Returned: SBObject
Duplicate one or more object(s)
----
Method: exists
Returned: BOOL
Verify if an object exists
----
Method: open
Returned: void
open the specified object(s)
----
Method: playOnce:(BOOL)once
Returned: void
play the current track or the specified track or file.
----
 
Class: iTunesApplication
Properties:
currentEncoder (the currently selected encoder (MP3, AIFF, WAV, etc.))
currentEQPreset (the currently selected equalizer preset)
currentPlaylist (the playlist containing the currently targeted track)
currentStreamTitle (the name of the current song in the playing stream (provided by streaming server))
currentStreamURL (the URL of the playing stream or streaming web site (provided by streaming server))
currentTrack (the current targeted track)
currentVisual (the currently selected visual plug-in)
EQEnabled (is the equalizer enabled?)
fixedIndexing (true if all AppleScript track indices should be independent of the play order of the owning playlist.)
frontmost (is iTunes the frontmost application?)
fullScreen (are visuals displayed using the entire screen?)
name (the name of the application)
mute (has the sound output been muted?)
playerPosition (the player’s position within the currently playing track in seconds.)
playerState (is iTunes stopped, paused, or playing?)
selection (the selection visible to the user)
soundVolume (the sound output volume (0 = minimum, 100 = maximum))
version (the version of iTunes)
visualsEnabled (are visuals currently being displayed?)
visualSize (the size of the displayed visual)
 
Method: browserWindows
Returned: SBElementArray
----
Method: encoders
Returned: SBElementArray
----
Method: EQPresets
Returned: SBElementArray
----
Method: EQWindows
Returned: SBElementArray
----
Method: playlistWindows
Returned: SBElementArray
----
Method: sources
Returned: SBElementArray
----
Method: visuals
Returned: SBElementArray
----
Method: windows
Returned: SBElementArray
----
Method: printPrintDialog:(BOOL)printDialog withProperties:(iTunesPrintSettings *)withProperties kind:(iTunesEKnd)kind theme:(NSString *)theme
Returned: void
Print the specified object(s)
----
Method: run
Returned: void
run iTunes
----
Method: quit
Returned: void
quit iTunes
----
Method: add:(NSArray *)x to:(SBObject *)to
Returned: iTunesTrack
add one or more files to a playlist
----
Method: backTrack
Returned: void
reposition to beginning of current track or go to previous track if already at start of current track
----
Method: convert:(NSArray *)x
Returned: iTunesTrack
convert one or more files or tracks
----
Method: fastForward
Returned: void
skip forward in a playing track
----
Method: nextTrack
Returned: void
advance to the next track in the current playlist
----
Method: pause
Returned: void
pause playback
----
Method: playOnce:(BOOL)once
Returned: void
play the current track or the specified track or file.
----
Method: playpause
Returned: void
toggle the playing/paused state of the current track
----
Method: previousTrack
Returned: void
return to the previous track in the current playlist
----
Method: resume
Returned: void
disable fast forward/rewind and resume playback, if playing.
----
Method: rewind
Returned: void
skip backwards in a playing track
----
Method: stop
Returned: void
stop playback
----
Method: update
Returned: void
update the specified iPod
----
Method: eject
Returned: void
eject the specified iPod
----
Method: subscribe:(NSString *)x
Returned: void
subscribe to a podcast feed
----
Method: updateAllPodcasts
Returned: void
update all subscribed podcast feeds
----
Method: updatePodcast
Returned: void
update podcast feed
----
Method: openLocation:(NSString *)x
Returned: void
Opens a Music Store or audio stream URL
----
 
Class: iTunesItem
Properties:
container (the container of the item)
index (The index of the item in internal application order.)
name (the name of the item)
persistentID (the id of the item as a hexidecimal string. This id does not change over time.)
 
Method: id
Returned: NSInteger
the id of the item
----
Method: printPrintDialog:(BOOL)printDialog withProperties:(iTunesPrintSettings *)withProperties kind:(iTunesEKnd)kind theme:(NSString *)theme
Returned: void
Print the specified object(s)
----
Method: close
Returned: void
Close an object
----
Method: delete
Returned: void
Delete an element from an object
----
Method: duplicateTo:(SBObject *)to
Returned: SBObject
Duplicate one or more object(s)
----
Method: exists
Returned: BOOL
Verify if an object exists
----
Method: open
Returned: void
open the specified object(s)
----
Method: playOnce:(BOOL)once
Returned: void
play the current track or the specified track or file.
----
Method: reveal
Returned: void
reveal and select a track or playlist
----
 
Class: iTunesPlaylist
Properties:
duration (the total length of all songs (in seconds))
name (the name of the playlist)
parent (folder which contains this playlist (if any))
shuffle (play the songs in this playlist in random order?)
size (the total size of all songs (in bytes))
songRepeat (playback repeat mode)
specialKind (special playlist kind)
time (the length of all songs in MM:SS format)
visible (is this playlist visible in the Source list?)
 
Method: tracks
Returned: SBElementArray
----
Method: moveTo:(SBObject *)to
Returned: void
Move playlist(s) to a new location
----
Method: searchFor:(NSString *)for_ only:(iTunesESrA)only
Returned: iTunesTrack
search a playlist for tracks matching the search string. Identical to entering search text in the Search field in iTunes.
----
 
Class: iTunesAudioCDPlaylist
Properties:
artist (the artist of the CD)
compilation (is this CD a compilation album?)
composer (the composer of the CD)
discCount (the total number of discs in this CD’s album)
discNumber (the index of this CD disc in the source album)
genre (the genre of the CD)
year (the year the album was recorded/released)
 
Method: audioCDTracks
Returned: SBElementArray
----
 
Class: iTunesDevicePlaylist
Method: deviceTracks
Returned: SBElementArray
----
 
Class: iTunesLibraryPlaylist
Method: fileTracks
Returned: SBElementArray
----
Method: URLTracks
Returned: SBElementArray
----
Method: sharedTracks
Returned: SBElementArray
----
 
Class: iTunesRadioTunerPlaylist
Method: URLTracks
Returned: SBElementArray
----
 
Class: iTunesSource
Properties:
capacity (the total size of the source if it has a fixed size)
freeSpace (the free space on the source if it has a fixed size)
kind ()
 
Method: audioCDPlaylists
Returned: SBElementArray
----
Method: devicePlaylists
Returned: SBElementArray
----
Method: libraryPlaylists
Returned: SBElementArray
----
Method: playlists
Returned: SBElementArray
----
Method: radioTunerPlaylists
Returned: SBElementArray
----
Method: userPlaylists
Returned: SBElementArray
----
Method: update
Returned: void
update the specified iPod
----
Method: eject
Returned: void
eject the specified iPod
----
 
Class: iTunesTrack
Properties:
album (the album name of the track)
albumArtist (the album artist of the track)
albumRating (the rating of the album for this track (0 to 100))
albumRatingKind (the rating kind of the album rating for this track)
artist (the artist/source of the track)
bitRate (the bit rate of the track (in kbps))
bookmark (the bookmark time of the track in seconds)
bookmarkable (is the playback position for this track remembered?)
bpm (the tempo of this track in beats per minute)
category (the category of the track)
comment (freeform notes about the track)
compilation (is this track from a compilation album?)
composer (the composer of the track)
databaseID (the common, unique ID for this track. If two tracks in different playlists have the same database ID, they are sharing the same data.)
dateAdded (the date the track was added to the playlist)
objectDescription (the description of the track)
discCount (the total number of discs in the source album)
discNumber (the index of the disc containing this track on the source album)
duration (the length of the track in seconds)
enabled (is this track checked for playback?)
episodeID (the episode ID of the track)
episodeNumber (the episode number of the track)
EQ (the name of the EQ preset of the track)
finish (the stop time of the track in seconds)
gapless (is this track from a gapless album?)
genre (the music/audio genre (category) of the track)
grouping (the grouping (piece) of the track. Generally used to denote movements within a classical work.)
kind (a text description of the track)
longDescription ()
lyrics (the lyrics of the track)
modificationDate (the modification date of the content of this track)
playedCount (number of times this track has been played)
playedDate (the date and time this track was last played)
podcast (is this track a podcast episode?)
rating (the rating of this track (0 to 100))
ratingKind (the rating kind of this track)
releaseDate (the release date of this track)
sampleRate (the sample rate of the track (in Hz))
seasonNumber (the season number of the track)
shufflable (is this track included when shuffling?)
skippedCount (number of times this track has been skipped)
skippedDate (the date and time this track was last skipped)
show (the show name of the track)
sortAlbum (override string to use for the track when sorting by album)
sortArtist (override string to use for the track when sorting by artist)
sortAlbumArtist (override string to use for the track when sorting by album artist)
sortName (override string to use for the track when sorting by name)
sortComposer (override string to use for the track when sorting by composer)
sortShow (override string to use for the track when sorting by show name)
size (the size of the track (in bytes))
start (the start time of the track in seconds)
time (the length of the track in MM:SS format)
trackCount (the total number of tracks on the source album)
trackNumber (the index of the track on the source album)
unplayed (is this track unplayed?)
videoKind (kind of video track)
volumeAdjustment (relative volume adjustment of the track (-100% to 100%))
year (the year the track was recorded/released)
 
Method: artworks
Returned: SBElementArray
----
 
Class: iTunesFileTrack
Properties:
location (the location of the file represented by this track)
 
Method: refresh
Returned: void
update file track information from the current information in the track’s file
----
 
Class: iTunesURLTrack
Properties:
address (the URL for this track)
 
Method: download
Returned: void
download podcast episode
----
 
Class: iTunesUserPlaylist
Properties:
shared (is this playlist shared?)
smart (is this a Smart Playlist?)
 
Method: fileTracks
Returned: SBElementArray
----
Method: URLTracks
Returned: SBElementArray
----
Method: sharedTracks
Returned: SBElementArray
----

framework 'ScriptingBridge'
app = SBApplication.applicationWithBundleIdentifier("com.apple.iChat")
original_status = app.statusMessage
new_year = Time.mktime(2010, 1, 1, 0, 0)
 
loop do
  now = Time.now
  time_left = (new_year - now).ceil
  if time_left > 0
    app.statusMessage = "#{time_left} seconds left until 2010 (EST)"
  else
    app.statusMessage = "Happy New Year 2010!"
    exit
  end
  sleep(1)
end

If you are alone at home playing WOW,  you can also trigger iTunes to play a mp3 file with crowd noise and people shouting ‘Happy New Year 2010‘!