Tuesday, February 09, 2016

MiniRxSwift

I wanted to provide asynchronous networking for my StockFighterApiClient library, but I had 2 problems

  • Callback-based asynchronous programming is not nice. It quickly leads to nested callback hell
  • The Reactive Framework provides a much nicer async model, and RxSwift is great. I've used it in other projects and I much prefer it to ReactiveCococa, however RxSwift is a multi-megabyte download with dozens of source files, and I want to keep the ApiClient library as self contained as possible
So, I wrote a small miniaturised version of RxSwift which only contains a few of the core operators.

RxSwift and ReactiveCocoa get bloated by UI bindings and stuff like that which are completely unnecessary for the core Rx functionality, so it's great not to have any of those

It's a single file, approx 400 lines including comments and whitespace, and you can find it here:
https://github.com/borland/StockFighterApiClient/blob/master/MiniRxSwift.swift

It is missing a few things which might end up being important, but even if those get added it will still remain a single file and I doubt it'd ever get over 1000 LOC.

While this is silly wheel re-inventing, and in a serious project I'd just use RxSwift, I found that there were some benefits that came of it.

Protocol Associated Types

It was the first time I'd used protocols with associated types in Swift before. Implementing Observable/Observer as protocols in swift was an interesting journey learning about how associated types worked, and how they are different to generics.

Overall I found associated types to be profoundly strange compared to anything I'd used before in other languages.
I can appreciate that associated types can be more powerful and flexible than generics, but I couldn't help feeling that I didn't actually want or need that extra power/flexibility, and the cost and complexity it imposes (having to create type-erased wrappers such as Apple's AnySequence, or my Observer class) was annoying.
I can't help but think that this is going to be somewhat of a pain for people as they learn swift. I can imagine trying to explain to a new developer on my team why we have to write wrapper classes to bridge between protocols and generics, and I'm pretty sure that's going to be a very confusing and difficult to grasp situation for a newbie.
At any rate, I learned a fundamentally new (to me) concept. That doesn't happen very often once you get past your first few years of programming, so it's been well worth the effort.

Learning/Refreshing Rx knowledge

At work, we've got a lot of C# code that uses the Reactive extensions for .NET. I initially learned Rx way back when it was a pre-release binary dll that Microsoft shipped (I vaguely recall) privately as a helper library in some version of Silverlight or something like that.
I learned it primarily by reading the decompiled source code using Reflector, as there wasn't any documentation or even an official download of Rx for quite some time.

This ended up being great for me, as I got a deep understanding of exactly what is going on behind the scenes for each method and task. No matter how good the documentation for something is, there's no substitute for knowing that (for example) a method takes a lock just before it does some critical thing and when it releases it.

I was only really able to do this though, because Rx back then was much smaller and simpler. The Rx of today has gone through many years of Architecting, Refactoring, Indirecting, Abstracting and Organising. While I've no doubt that it's benefitted the project overall, the downside is that everything is now very hard to find and to learn.
For example, take a look at SelectMany - It's 1739 lines of code just for that class, and to understand it you also need to know how it's base class works.
In contrast, the old original code for SelectMany (known as flatMap in languages other than C#), was a single function, and looked a lot like the one in MiniRxSwift which is entirely self contained, has no classes, and is under 40 LOC including whitespace.
The real RxSwift has taken the approach of porting from C#, so it keeps mostly the same class hierarchy and complexity as the C# implementation, and is equally hard to find your way around.

Hopefully someone one day can look at MiniRxSwift and get a better understanding of Rx

P.S.

I wrote most of this from my understanding of how Rx works. I did look at the Rx documentation, and I definitely looked at the RxSwift source code along the way - not to copy it - but to learn how they were doing things with Protocol-Associated-Types. The swift compiler produces a lot of confusing error messages if you get your generics/PAT bridging code wrong and I wouldn't have been able to do it without some reference code to learn from.

Thanks RxSwift!


Thursday, January 28, 2016

StockFighterApiClient

TL;DR

I wrote a client library in Swift for StockFighter. It's on github at https://github.com/borland/StockFighterApiClient, feel free to use it or check it out!



If you're a programmer and you haven't heard of it, I'd recommend checking out StockFighter.
It's a "programming game" wherein you have to write code to perform some task in a correct/fast/clever/etc way. In this specific instance, the goal is to write bots to perform high-frequency stock trading (well, actually pretty slow frequency trading compared to real stock markets, but much faster than a human would).

I'm midway through the third level so far, but I've found it quite interesting and challenging to think about some of the strategies for solving some of the problems.

The way it works is you write some code to connect to their cloud servers via a REST api (and/or WebSockets) and have your bot buy and sell stocks on their fake stock exchanges. Different levels have different challenges.

I'm a big fan of Swift at the moment, so I wanted to use it for stockfighter. Swift has

  • Nice syntax and a nice high level - I find swift code to be mostly similar to C#, but with less semicolons and brackets which is always great, and it's often more concise. Code is roughly about the same size as it would be in Ruby or JavaScript.
  • Decent functional programming style support - It has nice lambda functions, things like map/filter over collections are built in and you can extend existing types to add more complicated methods as needed)
  • Null safety - The compiler can enforce that things may or may not be null which is a bit weird at first, but once you get used to it is very nice. I find on average my swift code has a much higher chance of "just working on the first run" primarily due to this.
  • An exception model which I like - I always found Java's explicit checked exceptions to cause too much code bloat, especially having to declare catch blocks for multiple different exception types all over the place. At the same time, I've sometimes found the "transparent" exceptions of C# or C++ aren't as nice because often you simply won't be aware that a method could throw an exception until you find out later in a crash report. The swift model strikes a middle ground, and while it has some shortcomings too, on balance I like it better than either of the other approaches
  • Good performance - It seems to be roughly in the ballpark of C# or Java, but uses less memory and starts up faster due to lack of a "runtime" and garbage collector, which is great
Anyway, I looked online and found one existing client library - RSStockFighter, however, I wanted to write my own client library from the ground up for fun, and for practice.

Additionally RSStockFighter uses a "command object" pattern, wherein you create different kinds of objects representing each different request you might want to make, then you submit them to the server. While such a pattern offers many benefits and is probably good OO design, I find it adds friction to the programming experience and is not what I'd like to use (at least for a project the size of a stock fighter client. It might make more sense when you have an API with hundreds of methods).

Rather than this:

let order = StockFighterOrder(symbol:SF_STOCK_SYMBOL, price:95.00,qty: 100,direction:SF_OrderDirection.Buy,orderType:SF_OrderTypes.Limit.rawValue)
       
StockFighterHelper.sendStockFighterTransaction(order, success: {
    (dict:NSDictionary!) -> Void in
        self.checkOrderResponse(dict)
}, failure: {(str: String) -> Void in
        print(str)
})


I'd much rather write this:

let response = try venue.placeOrderForStock(SYMBOL, price: 9500, qty: 100, direction: .Buy)

HTTP calls in my library are synchronous, and either return a result or throw an exception, which generally makes the code shorter and clearer.

Personally I prefer asynchronous I/O, however then you have to deal with callbacks. The Reactive frameworks - RxSwift in this case - provide a much nicer model than the nested-callbacks approach, so I think if I were to provide async methods I'd use RxSwift - however that means if anyone wants to use my Api they must also take a dependency on RxSwift, so I left it out for now.

My library also provides access to the StockFighter web socket API using SocketRocket behind the scenes. I embedded a copy of SocketRocket in my github repo so there's only one thing to download, but adding third party frameworks such as SocketRocket to a project in Xcode is a bit of a pain. I've documented the process in my README, but it's still not ideal.

I didn't want to use something like CocoaPods / Carthage because they are yet another barrier to entry. I don't want to ask people to go and cruft up their system and install some magical dependency manager which is going to do who-knows-what when I could offer people a simpler "copy some files" option instead. Perhaps that's a topic for another post in future.

Anyway. Head over to github and check it out if you're interested. It's on github at https://github.com/borland/StockFighterApiClient and I'd appreciate any feedback!

Wednesday, March 25, 2015

Using ReactiveCocoa from Swift

We're trying out swift at work, and have an existing app which makes quite a bit of use of ReactiveCocoa.
Looking online, I found MVVM, Swift and ReactiveCocoa - It's all good! from Colin Eberhardt. It's a good intro, but I found I had trouble when trying to use the tricker subscribe overloads.

Without further ado, here's my own take on the extensions.
Licensing wise I declare it to be public domain, do with it as you will.
(Note: Implemented on Xcode 6.2 with Swift 1.1)


import Foundation

extension RACSignal {

    // Subscribe with an on-next block
    // Equivalent of - (RACDisposable *)subscribeNext:(void (^)(id x))nextBlock {
    func subscribe(next nextClosure:(T)->Void) -> RACDisposable {
        return self.subscribeNext { (x: AnyObject!) -> () in nextClosure(x as T) }
    }
    
    // Subscribe with an on-next and on-completed block
    // Equivalent of - (RACDisposable *)subscribeNext:(void (^)(id x))nextBlock completed:(void (^)(void))completedBlock;
    func subscribe(next nextClosure:(T)->Void, completed completedClosure:()->Void) -> RACDisposable {
        return self.subscribeNext(
            { (x: AnyObject!) -> () in nextClosure(x as T) },
            completed:{ () in completedClosure() })
    }
    
    // Subscribe with an on-next and on-error block
    // Equivalent of - (RACDisposable *)subscribeNext:(void (^)(id x))nextBlock error:(void (^)(NSError *error))errorBlock {
    func subscribe(next nextClosure:(T)->Void, error errorClosure:(NSError)->Void) -> RACDisposable {
        return self.subscribeNext(
            { (x: AnyObject!) -> () in nextClosure(x as T) },
            error:{ (x:NSError!) in errorClosure(x) })
    }
    
    // Subscribe with an on-next, on-error and on-completed block
    // Equivalent of - (RACDisposable *)subscribeNext:(void (^)(id x))nextBlock error:(void (^)(NSError *error))errorBlock completed:(void (^)(void))completedBlock;
    func subscribe(next nextClosure:(T)->Void, error errorClosure:(NSError)->Void, completed completedClosure:()->Void) -> RACDisposable {
        return self.subscribeNext(
            { (x: AnyObject!) -> () in nextClosure(x as T) },
            error:{ (x:NSError!) in errorClosure(x) },
            completed:{ () in completedClosure() })
    }
    
    // Subscribe with an on-error block
    // Equivalent of - (RACDisposable *)subscribeError:(void (^)(NSError *error))errorBlock;
    func subscribe(error errorClosure:(NSError)->Void) -> RACDisposable {
        return self.subscribeError { (x: NSError!) -> () in errorClosure(x) }
    }
    
    // Subscribe with an on-error and on-completed block
    // Equivalent of - (RACDisposable *)subscribeError:(void (^)(NSError *error))errorBlock completed:(void (^)(void))completedBlock;
    func subscribe(error errorClosure:(NSError)->Void, completed completedClosure:()->Void) -> RACDisposable {
        return self.subscribeError(
            { (x: NSError!) -> () in errorClosure(x) },
            completed:{ () in completedClosure() })
    }
}

Now, how to use it (this can be a bit unclear sometimes in swift)

To subscribe for on-next notifications


someSignal.subscribe { (arg:Type) in .... }

e.g. with an RACSignal publishing strings it would be
someSignal.subscribe { (x:String) in doSomething(x) }
or
someSignal.subscribe(
    next:{ (x:String) in 
        doSomething(x) 
    })

To subscribe for on-error notifications


someSignal.subscribe(error:{ (e) in .... })
or
someSignal.subscribe(
    error:{ (e) in 
        logError(e) 
    })


e.g. with an RACSignal publishing strings it would be
someSignal.subscribe(error:{ (e) in logError(e) }

You don't need to specify (error:NSError) as the compiler is smart enough to infer that, however you do need to specify the explicit error: parameter name, so the compiler knows this is an error handler, not an on-next handler

To subscribe for on-next and on-completed notifications


someSignal.subscribe({ (arg:Type) in .... }, completed:{ ... })

e.g. with an RACSignal publishing strings it would be
someSignal.subscribe({ (x:String) in doSomething(x) }, completed:{ allDone() })
or
someSignal.subscribe(
    next:{ (x:String) in 
        doSomething(x) 
    }, 
    completed:{ 
       allDone() 
    })


Warning If the code in your completed block (e.g. the allDone function) doesn't return void, the compiler will infer it as the return type of the completed block, and you'll get a confusing-looking Extra argument 'completed' in call error. The fix is to insert an explicit return, e.g.

someSignal.subscribe(
    next:{ (x:String) in 
        doSomething(x) 
    }, 
    completed:{ 
       allDone() 
       return
    })


To subscribe for on-next and on-error notifications


someSignal.subscribe({ (arg:Type) in .... }, error:{ (e) in ... })

e.g. with an RACSignal publishing strings it would be
someSignal.subscribe({ (x:String) in doSomething(x) }, error:{ (e) in logError(e) })
or
someSignal.subscribe(
    next:{ (x:String) in 
        doSomething(x) 
    }, 
    error:{ (e) in
       logError(e) 
    })


To subscribe for all 3 - on-next, on-error and on-completed notifications


someSignal.subscribe({ (arg:Type) in .... }, error:{ (e) in ... }, completed:{ ... })

e.g. with an RACSignal publishing strings it would be
someSignal.subscribe({ (x:String) in doSomething(x) }, error:{ (e) in logError(e) }, completed:{ allDone() })
or
someSignal.subscribe(
    next:{ (x:String) in 
        doSomething(x) 
    }, 
    error:{ (e) in
       logError(e) 
    },
    completed:{
        allDone()
    })


The warning above (sometimes you might need an explicit return in the completed block) applies here too.

To subscribe for on-error and on-completed notifications


someSignal.subscribe(error:{ (e) in ... }, completed:{ ... })

e.g. with an RACSignal publishing strings it would be
someSignal.subscribe({ error:{ (e) in logError(e) }, completed:{ allDone() })
or
someSignal.subscribe(
    error:{ (e) in
       logError(e) 
    },
    completed: {
        allDone()
    })


The warning above (sometimes you might need an explicit return in the completed block) applies here too.

Wrap-up

I hope this helps!

P.S. - if you're wondering where the "on-completed only" version is - there isn't one, because ReactiveCocoa doesn't seem to provide one for some reason. If you want that behaviour, you can subscribe with an empty on-next or on-error callback.

Monday, May 05, 2014

Codemania 2014 Presentation

I gave a presentation at Codemania 2014 titled "Understanding C++ Templates".

The abstract is as follows (posted here for posterity, as codemania will take all the 2014 details down when the 2015 conference ramps up)

Understanding C++ templates

Templates are a key feature of C++. They enable you to write safer code with less duplication and better performance. Almost all C++ programmers have encountered them, but few know them well. Orion will show you how to think about and put to use some of the more advanced things you can do with templates, and show that they're simpler than you might think.

Even if you're not a C++ developer, understanding these concepts will give you a better perspective for programming in other languages.

The source code/examples I used in the presentation are available here on Github

The slides are available on here on iCloud

Monday, November 11, 2013

Integrating an automated iOS build with a Windows Team Foundation Server build environment

My current job is a "Microsoft shop" - our source control is Microsoft's Team Foundation Server, we primarily write applications for windows using C++ and C#, and all the developers use windows workstation PC's.

We'd like to develop an iOS app, but we'd like to set it up with a repeatable, automatable build process. Simply asking the guy with the mac on his desk to compile a new build and hope it works doesn't cut it.
All our existing build processes are using Team Foundation Server's build agents and build scripts, which have some very nice properties, and we'd like to be able to queue and publish iOS builds in the same way.

The problem is that we must build iOS apps on a Mac using Xcode, but the Team Foundation Server build agent only runs on Windows

How do we bridge this gap? Using SSH from a windows build agent to a remote mac.

  • The TFS build script uses putty (specifically the command line plink application) to tell the mac to remotely do things.
  • We queue a TFS build onto one of our windows TFS build agent PC's. It basically just runs plink, captures the output and waits for it to exit.
  • We get the files from the TFS repository onto the mac via SCP - the windows TFS build agent checks everything out, then runs pscp to copy it all over to the mac
  • The mac then uses xcodebuild and xcrun to compile and package the iOS app for ad-hoc distribution
  • The windows build agent then uses pscp to copy the packaged iOS app off the mac back onto the windows build agent, which then copies it into the appropriate drop folder alongside all the other windows builds.
  • We host a basic web server to serve the iOS application's .ipa package over HTTP, and everyone installs/upgrades our app by accessing this webpage using iOS' over the air beta testing facilities.

There are a lot of pieces to this, particularly given that we do not want to put secure data such as user account passwords in source control or have them hardcoded into build scripts. Here are the details, in the order that (for me) makes the most sense.

Setting up the Mac


Install Xcode

Obviously we need to install Xcode on the mac. The easiest way is just via the Mac app store, but you can also download a DMG from the apple developer centre for offline installs.

Install Team Explorer Everywhere

I did this by unzipping microsoft's zip file into /usr/local/bin. There is likely a better/more modular way to manage this than putting everything directly in /usr/local/bin, but this works fine on my isolated build machine.

User account

In the interests of keeping the build environment clean, and repeatable (so we can set up other mac build machines easily in the future), we want all of the builds to be performed by a dedicated user account. We do not ever want to use this account to do normal day to day development. Ideally we should never log into it interactively at all, only via SSH. This helps ensure that our builds really are clean and repeatable, and that we don't end up with accidental dependencies on random files/data in a normal person's user account.

Enabling passwordless SSH logins

We need the windows build agent PC to SSH into the mac, but we don't want the TFS build scripts to have the password of the mac's build account, we want to enable passwordless logins. To do this, I followed the instructions here: http://www.tonido.com/blog/index.php/2009/02/20/ssh-without-password-using-putty/

Once this has been set up, on the mac the /Users/buildaccount/.ssh/authorized_keys file will contain the details of the ssh key, and on the windows PC there will be the matching .ppk file. We can use plink to get the mac to run various scripts, as follows

plink -ssh -batch -l buildaccount -i buildaccountkey.ppk mac01.domain.local /Users/buildaccount/build_script.sh

Enabling our non-admin account to login using SSH

Apple's default SSH security settings are such that only users with Admin rights can login via SSH (At least this is the case on OSX 10.9, which I am using). We want our build account to be a non-admin user, so we'll have to edit the access control list that controls who can access ssh, and add our build user to it.

sudo dseditgroup -o edit -n . -a buildaccount -t user com.apple.access_ssh

Setting up the build process


Certificates and Provisioning Profiles

As we're setting up for Ad-hoc deployment of our app, we need an iOS Distribution Certificate, and an Ad-hoc provisioning profile. You generate both of these via the Apple Developer website's Member Centre. When building through the Xcode UI, it handles most of this for you, but as we want to be building via the command line, and via SSH into a clean user account, we have a few more hoops to jump through.

Putting the certificates in a custom keychain

By default Xcode and it's command line tools will look for your distribution certificate in the user default keychain (the login keychain). As we want our build account to be "clean", we don't want to have to put them in the build account's login keychain. To resolve this, we can create a custom keychain, and put the certificates/provisioning profile keys in there.

We can then decide to either check this custom keychain file into source control, or put it in some other special location.

I'm assuming that you've already created and loaded/installed a distribution certificate, and an ad-hoc provisioning profile.

  1. From your normal user account, run Keychain Access
  2. Right-click on the list of keychains in the top-left, and create a new keychain. Give it a meaningful filename and store it somewhere you can find later.
  3. From your login keychain, hold the option key (to copy) and drag your iPhone Distribution certificate, and the Ad-hoc distribution private key.

Using this custom keychain in the build script

To get the Xcode command line tools to use this custom keychain file, add the following before you invoke xcodebuild

keychain_file="$SCRIPTPATH/iOSCustomBuild.keychain"
keychain_pass=secretpassword
security list-keychains -s "$keychain_file" ~/Library/Keychains/login.keychain  # put the iOS keychain in ahead of the login keychain
security unlock-keychain -p "$keychain_pass" "$keychain_file"

The security list-keychains -s command sets the search order, telling the system first to look in our custom keychain, followed by the default login keychain. This command is persistent - I haven't worried about resetting it after our script completes, but you may want to

The security unlock-keychain command is required because keychains are locked by default when code is run in a remote SSH session. We must issue security unlock-keychain or else xcodebuild will not be able to read the keychain. This is another reason to use a custom keychain file - if we were using the user's login keychain, we would be required to hard code the user account's password into our build scripts.

Compiling and packaging the app

To build our iOS app, we'll need to run xcodebuild, which is xcode's command line build tool. This requires a number of flags, which we will create variables for and then re-use. Here's mine:

# hack to get the full path to the current directory
pushd `dirname $0` > /dev/null
SCRIPTPATH=`pwd`
popd > /dev/null

application_name=MyiOSApp # our app name - should correspond to MyiOSApp.xcodeproj
sdk="iphoneos7.0" # which version of iOS are we targeting

# Name of the distribution certificate. Get this by downloading the certificate from 
# the apple developer center, installing it, and then viewing it's name in keychain
codesign="iPhone Distribution: My Name (AAA12345ZZ)"

# build the project (must sign as xcode requires signing for all non-simulator bulds)
# CONFIGURATION_BUILD_DIR is only required for cordova/phonegap projects.
xcodebuild -project "$SCRIPTPATH/$application_name.xcodeproj" -target $application_name -configuration Release -sdk $sdk clean build CODE_SIGN_IDENTITY="$codesign" CONFIGURATION_BUILD_DIR="$SCRIPTPATH/build"

This only gets us halfway - xcodebuild will produce a .app package (a directory). This doesn't have the provisioning profile embedded in it, and we also need to package it up as a .ipa file to distribute it via the ad-hoc mechanisms. To do this step, we'll need to run xcrun. Here's my part of the script to do that:

# Get this by downloading it from the apple developer center
provisioning_profile_file="$SCRIPTPATH/My_Ad_Hoc_Provisioning_Profile.mobileprovision"
provisioning_profile_name="My Ad Hoc Provisioning Profile" # get this from the apple developer center when you download the file

# install the provisioning profile so xcode can use it 
provisioning_profile_uuid=`grep UUID -A1 -a "$provisioning_profile_file" | grep -o "[-A-Z0-9]\{36\}"`
cp "$provisioning_profile_file" ~/Library/MobileDevice/Provisioning\ Profiles/$provisioning_profile_uuid.mobileprovision
 
# this is where xcode will drop it's output, as a .app package
build_dir="$SCRIPTPATH/build"

# this is where we want the created .ipa file to be put
drop_dir="$SCRIPTPATH"

# package it and embed the provisioning profile (must re-sign as packaging alters the app)
/usr/bin/xcrun -sdk $sdk PackageApplication -v "${build_dir}/${application_name}.app" -o "${drop_dir}/${application_name}.ipa" --sign "$codesign" --embed "$provisioning_profile_file"

I chose to simply check my provisioning profile file into source control.

Also note that we have the extra step of "installing" the provisioning profile. This is because we're trying to run under a clean account. If we were running as a normal user account where someone had manually run Xcode, Xcode would have put the provisioning profile into the ~/Library/MobileDevice/Provisioning Profiles directory already for us and we wouldn't need to do this step.

The full build script


keychain_file="$SCRIPTPATH/iOSCustomBuild.keychain"
keychain_pass=secretpassword
security list-keychains -s "$keychain_file" ~/Library/Keychains/login.keychain  # put the iOS keychain in ahead of the login keychain
security unlock-keychain -p "$keychain_pass" "$keychain_file"

# hack to get the full path to the current directory
pushd `dirname $0` > /dev/null
SCRIPTPATH=`pwd`
popd > /dev/null

application_name=MyiOSApp # our app name - should correspond to MyiOSApp.xcodeproj
sdk="iphoneos7.0" # which version of iOS are we targeting

# Name of the distribution certificate. Get this by downloading the certificate from 
# the apple developer center, installing it, and then viewing it's name in keychain
codesign="iPhone Distribution: My Name (AAA12345ZZ)"

# build the project (must sign as xcode requires signing for all non-simulator bulds)
# CONFIGURATION_BUILD_DIR is only required for cordova/phonegap projects.
xcodebuild -project "$SCRIPTPATH/$application_name.xcodeproj" -target $application_name -configuration Release -sdk $sdk clean build CODE_SIGN_IDENTITY="$codesign" CONFIGURATION_BUILD_DIR="$SCRIPTPATH/build"

# Get this by downloading it from the apple developer center
provisioning_profile_file="$SCRIPTPATH/My_Ad_Hoc_Provisioning_Profile.mobileprovision"
provisioning_profile_name="My Ad Hoc Provisioning Profile" # get this from the apple developer center when you download the file

# install the provisioning profile so xcode can use it 
provisioning_profile_uuid=`grep UUID -A1 -a "$provisioning_profile_file" | grep -o "[-A-Z0-9]\{36\}"`
cp "$provisioning_profile_file" ~/Library/MobileDevice/Provisioning\ Profiles/$provisioning_profile_uuid.mobileprovision
 
# this is where xcode will drop it's output, as a .app package
build_dir="$SCRIPTPATH/build"

# this is where we want the created .ipa file to be put
drop_dir="$SCRIPTPATH"

# package it and embed the provisioning profile (must re-sign as packaging alters the app)
/usr/bin/xcrun -sdk $sdk PackageApplication -v "${build_dir}/${application_name}.app" -o "${drop_dir}/${application_name}.ipa" --sign "$codesign" --embed "$provisioning_profile_file"

Putting it all together

All we need to do now is create TFS build script which Exec's plink and pscp and asks the mac to run the various .sh scripts which do all the work. Here's some snippets which you could use


<PropertyGroup>
    <!-- general -->
    <IpaFileName>MyiOSApp.ipa</IpaFileName>
    
    <!--File locations on the windows build machine-->
    <Plink>pathtoPLINK.EXE</Plink>
    <Pscp>pathtoPSCP.EXE</Pscp>
    
    <!--SSH connection info-->
    <SshHost>mac.domain.local</SshHost>
    <SshKey>buildaccountkey.ppk</SshKey>
    <SshUser>buildaccount</SshUser>

    <!--File locations on the mac-->
    <RemoteiOSBuildPath>/Users/buildaccount/iOSBuild</RemoteiOSBuildPath>
    <RemoteBuildScriptPath>$(RemoteiOSBuildPath)/build.sh</RemoteBuildScriptPath>
    <RemoteIpaFilePath>$(RemoteiOSBuildPath)/$(IpaFileName)</RemoteIpaFilePath>
</PropertyGroup>

...

<!--this "echo y | exit" causes plink/putty to cache the remote host key in the registry for subsequent operations.-->
<Exec command="echo y | &quot;$(Plink)&quot; -ssh -l $(SshUser) -i $(SshKey) $(SshHost) exit"/>

<!--Wipe any old files-->
<Exec command="&quot;$(Plink)&quot; -ssh -batch -l $(SshUser) -i $(SshKey) $(SshHost) rm -rf $(RemoteiOSBuildPath)" />
<Exec command="&quot;$(Plink)&quot; -ssh -batch -l $(SshUser) -i $(SshKey) $(SshHost) mkdir -p $(RemoteiOSBuildPath)" />

<!-- copy the source over to the mac -->
<Exec command="&quot;$(Pscp)&quot; -sftp -batch -r -i $(SshKey) -l $(SshUser) &quot;$(SolutionRoot)*&quot; $(SshHost):$(RemoteiOSBuildPath)" />

<!--run the build script-->
<Exec command="&quot;$(Plink)&quot; -ssh -batch -l $(SshUser) -i $(SshKey) $(SshHost) chmod +x $(RemoteBuildScriptPath)"/>
<Exec command="&quot;$(Plink)&quot; -ssh -batch -l $(SshUser) -i $(SshKey) $(SshHost) $(RemoteBuildScriptPath)"/>

<!-- copy the packaged ipa file back -->
<Exec command="&quot;$(Pscp)&quot; -sftp -batch -i $(SshKey) -l $(SshUser) $(SshHost):$(RemoteIpaFilePath) ." />

Wednesday, October 02, 2013

Programmatically controlling Hyper-V Server 2012 R2 virtual machines from C#

Recently I've wanted to remote control some virtual machines on a Hyper-V server in aid of automated testing.
I've got a server set up running Hyper-V Server 2012 R2, so the code samples in this are likely to work against Server 2012 non-R2, but may not work against Server 2008.

All the virtual machines start off at a known clean snapshot, and have a startup script which runs on boot that goes and asks a central database for a testing job to execute. So, for our system to work, we need to accomplish the following:
  1. Roll back a VM to the last known snapshot / checkpoint
  2. Power it on
There are several other things we need to do for this to work at all, which are:
  1. Connect to the Hyper-V server (this includes authentication)
  2. List out or otherwise ask the server about it's VM's so that we can rollback the correct one

To achieve thisk I'm using Hyper-V's WMI provider (V2). I don't really know much about WMI, so these code samples are just things I've hacked together. They are NOT production quality and they don't handle errors well or anything else. Please use them as guidance, not for copy/pasting.

Pre-requisites

Using WMI from C# is done by the classes in the System.Management namespace. To access this you'll want using System.Management at the top of your C# file, as well as a reference to the System.Management assembly.

Connecting and Logging on


To do this we need to create a ManagementScope object set to use the appropriate server and using the Hyper-V virtualization v2 namespace, and we also need to supply the username and password of a windows account that has privileges to administer the Hyper-V server. I did it like this:

var connectionOptions = new ConnectionOptions(
    @"en-US",
    @"domain\user",
    @"password",
    null,
    ImpersonationLevel.Impersonate, // I don't know if this is correct, but it worked for me
    AuthenticationLevel.Default,
    false,
    null,
    TimeSpan.FromSeconds(5);

var scope = new ManagementScope(new ManagementPath { 
    Server = "hostnameOrIpAddress", 
    NamespacePath = @"root\virtualization\v2" }, connectionOptions);
scope.Connect();

Note: Most of the other documentation or sample code I found refers to the root\virtualization namespace. This didn't work at all for me in Server 2012 R2, and I had to use dotPeek to decompile the Hyper-V powershell commandlets to figure out to put \v2 on the end. Perhaps the non-v2 one is for Server 2008?

Note: If your PC and the target server are on the same domain, and your windows user account has privileges to administer the remote server, You don't need the ConnectionOptions object at all. WMI will use windows authentication, and it will magically work:

Listing out the VM's and finding the one we want

Virtual machines in Hyper-V get exposed via the Msvm_ComputerSystem WMI class. In order to list them out, we simply ask WMI to give us all the objects of that class in the virtualization namespace. To do this, I'm going to create two helper extension methods, that we'll use from hereon:

public static class WmiExtensionMethods
{
    public static ManagementObject GetObject(this ManagementScope scope, string serviceName)
    {
        return GetObjects(scope, serviceName).FirstOrDefault();
    }
    
    public static IEnumerable<ManagementObject> GetObjects(this ManagementScope scope, string serviceName)
    {
        return new ManagementClass(scope, new ManagementPath(serviceName), null)
            .GetInstances()
            .OfType<ManagementObject>();
    }
}

It turns out that the Host PC is also exposed via Msvm_ComputerSystem, so we need to filter out things that are not virtual machines. This helper method will return a list of all the virtual machines. Note: I like extension methods, so I'm using them a lot here:

public static IEnumerable<ManagementObject> GetVirtualMachines(this ManagementScope scope)
{
    return scope.GetObjects("Msvm_ComputerSystem").Where(x => "Virtual Machine" == (string)x["Caption"]);
}

You can use it to get a specific virtual machine as follows:

var vm = scope.GetVirtualMachines().First(vm => vm["ElementName"] as string == "myvmname");

Rolling the VM back to it's latest snapshot / checkpoint

In order to roll a Hyper-V VM back to a snapshot, we need to get a reference to the snapshot object itself.

There are ways to simply list all the snapshots for each VM, but there is also a special Msvm_MostCurrentSnapshotInBranch class which represents the "latest" snapshot. We can use it to create a helper method as follows:

public static ManagementObject GetLastSnapshot(this ManagementObject virtualMachine)
{
    return virtualMachine.GetRelated(
        "Msvm_VirtualSystemSettingData",
        "Msvm_MostCurrentSnapshotInBranch",
        null,
        null,
        "Dependent",
        "Antecedent",
        false,
        null).OfType<ManagementObject>().FirstOrDefault();
}

And use it like this:

var snapshot = vm.GetLastSnapshot();

Now, to actually roll the VM back, we need to call the ApplySnapshot method on the Msvm_VirtualSystemSnapshotService class.
Note: Logically I thought that the snapshot methods should be on the Virtual Machine object, but Hyper-V puts them all in their own service for some reason. There is also only one global Snapshot service - not a service per VM. I've no idea why they've designed it this way.

We can create a helper method:

public static uint ApplySnapshot(this ManagementScope scope, ManagementObject snapshot)
{
    var snapshotService = scope.GetObject("Msvm_VirtualSystemSnapshotService");

    var inParameters = snapshotService.GetMethodParameters("ApplySnapshot");
    inParameters["Snapshot"] = snapshot.Path.Path;
    var outParameters = snapshotService.InvokeMethod("ApplySnapshot", inParameters, null);
    return (uint)outParameters["ReturnValue"];
}

And use it like this:

scope.ApplySnapshot(snapshot);

When I execute this with valid parameters, the VM applied it's snapshot, and I always got a return value of 4096. According to the documentation, this indicates that there's a Job in progress to asynchronously track the actual snapshot applying and determine the final success or failure. We could fetch the job out of outParameters["Job"] and use it to determine when the apply completes, but I'm not going to worry about that here. Refer to the ApplySnapshot MSDN page for other possible return codes.

Note: If the VM is not powered off, you are likely to find the ApplySnapshot call fails. You must power the VM off (and wait for the Power Off job to complete) first.

Powering on the VM to boot it up


Turning on the VM is done by the RequestStateChange method on the Msvm_ComputerSystem class. We already have the Msvm_ComputerSystem object representing the virtual machine we found earlier, so we can create a helper method and enumeration like this:

public enum VmRequestedState : ushort
{
    Other = 1,
    Running = 2,
    Off = 3,
    Saved = 6,
    Paused = 9,
    Starting = 10,
    Reset = 11,
    Saving = 32773,
    Pausing = 32776,
    Resuming = 32777,
    FastSaved = 32779,
    FastSaving = 32780,
}

public static uint RequestStateChange(this ManagementObject virtualMachine, VmRequestedState targetState)
{
    var managementService = virtualMachine.Scope.GetObject("Msvm_VirtualSystemManagementService");

    var inParameters = managementService.GetMethodParameters("RequestStateChange");
    inParameters["RequestedState"] = (object)targetState;
    var outParameters = virtualMachine.InvokeMethod("RequestStateChange", inParameters, null);
    return (uint)outParameters["ReturnValue"];
}

And use it like this:

vm.RequestStateChange(VmRequestedState.Running);

As for ApplySnapshot, when things work, the return value is usually 4096, indicating there is a Job to asynchronously track the progress of the operation.

Note: Although we invoke the method on the Msvm_ComputerSystem object, we need to get the method parameters by asking the Msvm_VirtualSystemManagementService object (which represents the host server) instead. I've no idea why.

Final fixups


ApplySnapshot will fail if the virtual machine is running. To turn it off, we can simply call vm.RequestStateChange(VmRequestedState.Off); and wait a bit for Job to complete.

RequestStateChange will fail if the state doesn't make sense. For example, if you try and turn the vm Off when it's already Off, the method will fail. You can check the current state of a Vm by reading it's EnabledState property. Valid values for EnabledState are documented with the Msvm_ComputerSystem class. I created an enum, and used it as follows:

public enum VmState : ushort
{
    Unknown = 0,
    Other,
    Running, // Enabled
    Off, // Disabled
    ShuttingDown,
    NotApplicable,
    OnButOffline,
    InTest,
    Deferred,
    Quiesce,
    Starting
}

if ((VmState)vm["EnabledState"] != VmState.Off)
{
    vm.RequestStateChange(VmRequestedState.Off); // needs to be off to apply snapshot
    Thread.Sleep(2000); // todo wait for the state change properly
}

You can do many more things by using other methods and classes from the Hyper-V WMI API. Hopefully this gives you a decent starting point.

P.S. The Hyper-V powershell commandlets are all implemented on top of this WMI Api. Using a tool like .NET reflector or dotPeek is an interesting way to see how Microsoft calls the WMI API.

Wednesday, September 05, 2012

TechEd 2012 background 2 - Compiler optimizations and Volatile

Note: This goal of this post is to provide more in-depth information and reference for attendees about a presentation I'm giving at Tech Ed New Zealand 2012.
The session is DEV402 - Multithreaded programming in .NET from the ground up.

This second post shows one possible effect of compiler optimizations on a C# program, and explains how to fix it using the oft-misunderstood volatile keyword.

Here's a sample program which illustrates this.
This program looks suspiciously similar to one of the samples in Joseph Albahari's threading book because that was by far the best piece of code I found or could invent to best illustrate the issue. All credit due to Joseph for his great work


class Program
{
    static int stopFlag = 0;

    static void ThreadProc()
    {
        Console.WriteLine("{0}: worker thread start", DateTime.Now.TimeOfDay);
        bool toggle = false;

        while (stopFlag == 0)
        {
            toggle = !toggle;
        }
        Console.WriteLine("{0}: worker thread done", DateTime.Now.TimeOfDay);
        Console.ReadLine();
    }

    public static void Main(string[] args)
    {
        stopFlag = 0;
        var t = new Thread(ThreadProc);
        t.Start();
        Thread.Sleep(1000);

        stopFlag = 1;

        Console.WriteLine("waiting...");
        t.Join();
    }
}


In summary, it's pretty simple. The main thread spins up a worker thread, sleeps for a second, then sets the stopFlag. The worker thread sits on a loop waiting for the stopFlag to be set, then exits.

If you run a Debug build of this code, or launch a 32-bit Release build with the debugger attached, you'll get this output:

10:38:25.0815053: worker thread start
waiting...
10:38:26.0955150: worker thread done

However, if you launch a 32-bit Release build without the debugger attached, you'll see this:

10:51:47.1955922: worker thread start
waiting...

The worker thread won't stop, and if you launch Task Manager you'll see that the app is thrashing away using an entire CPU. What's going on here?

To answer this, we need to attach the debugger to the already-running program, pause it and jump over to the worker thread and see what it's up to. The process for this in Visual Studio 2010/2012 goes like this:

  • From the Debug menu, chose Attach to Process...
  • Scroll down the list, select your application, and click Attach
  • Once the attach dialog closes, pause the application by clicking the pause button on the toolbar, or selecting Break All from the Debug menu. This will stop the program looping and let us look at what it's up to
  • Bring up the threads window, ( Debug / Windows / Threads ) and double-click on the worker thread

We should now see the current line of code that is being executed by this thread, which is

while (stopFlag == 0)

So, we're still in the loop waiting for the stopFlag to be set - yet, if you mouse over the stopFlag variable, or Add it to the Watch window, we'll see that it has a value of 1

The flag has been set, but our loop is still going. What gives?
To answer this, we need to bring up the Disassembly window. ( Debug / Windows / Disassembly ). This window shows us the raw x86 machine code that has been generated by the JIT compiler, and is the actual code that is being executed on the CPU.

The VS disassembly window will print each line of C# source code (if it has it), followed by the x86 assembly. For the line we're stuck on, we get this:

while (stopFlag == 0)
0000004a  mov         eax,dword ptr ds:[007A328Ch] 
0000004f  test        eax,eax 
00000051  jne         00000057 
00000053  test        eax,eax 
00000055  je          00000053 

If you know how to read x86 assembly, I congratulate you. I only know the basics, but enough that I can walk you through it and show what's going on.

So first, this line:

0000004a mov eax,dword ptr ds:[007A328Ch]

  • The instruction is mov which is x86 for "set something". The first parameter is the target, and the second is the source.
  • The First parameter is eax which refers to the EAX register inside the CPU. Intel x86 processors have 4 general purpose registers - EAX through EDX - that are used to perform the vast majority if work that happens in an application.
  • The Second parameter is dword ptr ds:[007A328Ch]. The dword ptr bit is a Size directive ( see this page and scroll down to "Size Directives" ) and it's needed to tell the CPU how many bytes we should be moving. dword ptr simply means 32 bits. I'm not entirely sure what the ds: bit means, but the most important part is this: [007A328Ch]. The square brackets mean "the value in memory at the given location". Our stop flag is static, so it's stored in a fixed memory location, in my case 007A328C

Translated: "Fetch 32 bits from memory at location 007A328C, and put them in the EAS register." In other words - load our stopflag into the CPU

The next part is this:
0000004f test eax,eax
00000051 jne 00000057


  • The test eax,eax is basically asking the question "Does EAX contain zero?"
  • The jne 00000057 is the Jump-if-not-equal instruction. It translates to "If it was NOT zero, jump to line 57

We know however, that when the loop starts, the flag was in fact zero, so we'll get past this block and onto the next one:

00000053 test eax,eax
00000055 je 00000053


  • Again, "Does EAX contain zero?"
  • The je 00000053 is the Jump-if-equal instruction. It translates to "If it WAS zero, jump to line 53, which is the start of our loop

Putting this all together, we end up with this sequence of events:

  • Load the stopflag from memory into EAX
  • Loop waiting for EAX to become non-zero

The problem is, at no point does any code ever set eax once we enter the loop.

What's going on here? The answer is that the C# and JIT compiler only consider the single-threaded case when doing optimizations. From the point of view of the WorkerThread, we never set the stopFlag, and we never call any other functions, so there is no possibility that the stopFlag can change. The JIT compiler can apply this, and decide that it only needs to read the stopFlag a single time, leading to this infinite loop!

To fix it, we simply mark the stopFlag variable as volatile.

This causes the assembly to change to this:

0000004a cmp dword ptr ds:[0088328Ch],0
00000051 jne 0000005C
00000053 cmp dword ptr ds:[0088328Ch],0
0000005a je 00000053


The key difference is that we see [0088328Ch] in the repetitive part of the loop. This means that at each iteration through the loop we go to memory and read the value. This means that when the stopFlag gets set after a second, we'll re-read it and the program behaves correctly. Great!

Discussion


There are a couple of things I'd like to go into more detail about:

Firstly, the weird double-check that the compiler generates for loops.
When the JIT compiler generates a loop it always seems to use this pattern:

  • First, check the opposite of the loop condition. If this is true, jump over the entire loop code
  • Now we enter the loop where we do the repeated action, and check the actual loop condition

Technically, there's no reason why we need to check it twice, we could get by with just the second part where we check the positive loop condition. I've no expert, but from what I can guess this is probably to help with branch prediction.
My personal theory is that by splitting the loop into 2 conditions, the branch predictor can track them both seperately.
If we bail out of the loop before it even gets started, the branch predictor won't need to worry about the subsequent code, but if we enter the second phase of the loop, the odds are good that we'll keep looping, so the branch predictor can use this information.

Secondly, the use of the cmp instruction rather than test in the loops
This stackoverflow question/answer sheds some light on the topic

The test instruction is smaller (different x86 instructions take different numbers of bytes to encode) than cmp, so the compiler will prefer it over cmp where both would achieve the same result. test works by doing a bitwise AND on the two values, whereas cmp does subtraction.

In the first case, where the value has already been loaded into a register, ANDing it with itself is a nice fast way to check for zero. In the second case however, where the value is being read from memory every time, in order to use test, we'd have to either use an extra register to store it in, or read the memory twice for both sides of the test operation. Both of which would be slower than against the constant 0.

Thirdly, what happened to the toggling inside the loop?
You may have noticed that the disassembly at no point shows anything to do with the loop body of toggle = !toggle;.

This is just the compiler optimizer doing it's job.

toggle is a local variable, it's not returned, and it's not passed to any functions - therefore, whatever we do to it can have no possible effect on anything. The compiler detects this, and simply removes it entirely.

So, what does this mean about volatile?
There seems to be a lot of confusion around what the volatile keyword is supposed to do. There are many questions/answers and blog posts which attempt to explain it. Some say say that it will insert memory barriers either before or after writes to the variable, some say that it causes reads and writes to be translated to calls to the Thread.VolatileRead or VolatileWrite method (both of which insert explicit barriers - but as we can see from our disassembly, it isn't inserting any such barriers, it's just doing normal ordinary reads and writes.

I think a lot of this confusion comes from the MSDN volatile documentation. The first hit in google for "C# Volatile Keyword" is the MSDN documentation, which states The system always reads the current value of a volatile object at the point it is requested, even if the previous instruction asked for a value from the same object. Also, the value of the object is written immediately on assignment.

In order for this to be true (particularly the "value is written immediately" part) one might infer that the compiler would insert memory barriers. Unfortunately, this page is the documentation for Visual Studio 2003. Subsequent revisions (2005, 2010, etc) re-word the documentation to be less misleading, but unfortunately google is still linking everyone to the old out of date page! For more, see http://www.albahari.com/threading/part4.aspx#_The_volatile_keyword

Additionally, the ECMA CLI spec states that reads to volatile fields should have acquire semantics, and writes to volatile fields should have release semantics. This could also cause people to think that memory barriers might be neccessary, but reads and writes on x86 already have these semantics anyway, so the net effect of volatile (other than compiler optimizations) is... Nothing!. On ARM or Itanium however, the JIT will insert memory barriers around reads and writes to volatile fields to give you the acquire/release semantics, as those CPU's don't guarantee it natively.