Gilt recently released Mockingbird Toolbox, an open-source project for iOS intended to make common development tasks easier. The Toolbox is the basic building block of Mockingbird library, which will be released in stages over the coming months. Mockingbird serves as the base layer of Gilt’s award-winning iPhone and iPad applications.

This post is the first in a series that will be highlighting the code available in Mockingbird Toolbox and explaining how you can use it in your iOS projects.


Modularity in software design is a key strategy for managing complexity. A well-crafted code module is:

  • Focused — it tries to do one main thing; anything else it does is in support of that
  • Isolated — it reduces interconnections within code by providing a public API that minimizes the points of contact between modules
  • Well-behaved — it doesn’t change global state in a way that interferes with other modules

When separate modules need to interact with a shared resource, modularity becomes more difficult to attain.

In order to be well-behaved, modules need to use shared resources in a way that recognizes the fact that other modules may be using that resource, too.

One way to try to account for that might be to introduce a mechanism for modules to communicate with each other to ensure proper behavior with respect to the shared resource. But doing so would make the modules less focused and isolated.

Gilt’s mobile team faced these sorts of design decisions during the evolution of our iOS apps. One generic solution we built was the MBServiceManager class, which we’ll discuss further in a future post.

But there was one specific shared resource that required its own solution: namely, the network indicator that appears in the status bar.

The Status Bar Network Indicator

The network indicator is the animated spinner that you sometimes see in the status bar, typically to the right of the other network information in the upper-left corner of the device screen.

The spinner doesn’t appear automatically; instead, applications are responsible for turning it on when they’re using the network, and turning it back off once they’re done. Displaying the network indicator is entirely optional, but polite applications are honest about when they’re consuming the user’s bandwidth.

Applications control the spinner through the UIApplication’s networkActivityIndicatorVisible property. Setting the value to YES causes the animated spinner to appear. Setting the property back to NO hides the spinner.

You might think that managing the network indicator is as simple as setting networkActivityIndicatorVisible to YES when an operation starts and back to NO when it finishes, but consider what happens when an app sends multiple network requests:

  1. Network operation A starts
  2. Network operation B starts
  3. Network operation B completes
  4. Network operation C starts
  5. Network operation A completes
  6. Network operation C completes

Under this scenario, the spinner should be animating from Step 1 through Step 6.

But that’s not what happens if we directly manipulate the networkActivityIndicatorVisible property at the start and end of each request. Instead, we get this behavior:

  1. Spinner appears
  2. Spinner animating
  3. Spinner disappears
  4. Spinner appears
  5. Spinner disappears
  6. Spinner remains hidden

Half the time, the network indicator is reflecting the wrong state.

Because the beginning and end of different network operations can be interleaved, the fact that there is only a single on/off value for the network indicator becomes problematic. If more than one set of code attempts to directly manipulate the value of networkActivityIndicatorVisible, we will get unexpected results.

Network Indicator Coordination

To avoid this problem, we decided upon creating a coordinator for the network indicator. The coordinator provides a simple interface for reporting when operations begin and end. Wherever network operations are performed, our code interacts with the coordinator, which in turn decides when to show and hide the spinner based on what’s happening across the entire application at any given moment.

The coordinator was designed to:

  • Maintain a count of in-progress network operations
    • Whenever an operation starts, the count would increment
    • Whenever one completes, the count would decrement
  • Set networkActivityIndicatorVisible property to YES whenever the count increases from 0 to 1

  • Set networkActivityIndicatorVisible property to NO whenever the count decreases from 1 to 0

  • Operate correctly in a multi-threaded environment

Introducing MBNetworkIndicator

The public interface to our coordinator is provided by the MBNetworkIndicator class, part of the Mockingbird Toolbox open-source project.

Any code that issues network requests can maintain one or more MBNetworkIndicator objects. Each instance is intended to represent one or more related network operations occurring on a single thread. While those operations are in progress, the MBNetworkIndicator instance is kept around, and is notified when operations begin and end.

The API consists of three instance methods:

  • operationStarted — Called whenever a network operation begins
  • operationFinished — Called whenever a network operation completes
  • cancelOperations — Called to signal that all in-progress operations associated with that specific instance should be considered finished (equivalent to calling operationFinished once for each in-progress operation)


Every MBNetworkIndicator instance maintains a counter of network operations that is incremented for each call to its operationStarted method and decremented for each call to its operationFinished method.

Calls to those methods also update a master counter, which keeps a single, application-wide count of in-progress operations.

You can think of it this way:

  • The count maintained by any given MBNetworkIndicator instance is equal to (the number of times its operationStarted method was called) minus (the number of times its operationFinished method was called)

  • The master count is equal to (the number of times operationStarted was called on all MBNetworkIndicator instances) minus (the number of times operationFinished was called on all MBNetworkIndicator instances)

Whenever the master count of network operations is greater than zero, the status bar network indicator is displayed. Otherwise, when there are no operations, the indicator is hidden.

Canceling Operations

Let’s say you have a UINavigationController-based app, and any given UIViewController pushed onto the navigation stack could result in multiple network requests being issued. Further, you handle the user tapping the Back button by hooking into viewWillDisappear: to cancel any network operations that haven’t yet finished.

In such a case, you might opt to have each UIViewController maintain its own MBNetworkIndicator instance. You would call operationStarted and operationFinished as requests are processed normally. But within viewWillDisappear:, you would call cancelOperations to signal that all pending operations for that view controller have been cancelled.

Calling cancelOperations is equivalent to calling operationFinished once for each pending operation.

Maintaining References

To ensure that the master counter balances over time, MBNetworkIndicator assumes that when an instance is deallocated, it is a signal that there are no related network operations still pending. (This is achieved by a call to cancelOperations from within dealloc.)

Because of this, you are expected to maintain strong references to MBNetworkIndicator instances that are still tracking pending operations.

Thread Safety

Because individual network operations are bound to specific threads, MBNetworkIndicator instances are designed to be used only on a single thread; instances must not be shared across threads.

However, the underlying mechanism that maintains the master counter and manages showing and hiding the network activity indicator is thread-safe.

The mechanism uses functions declared in <libkern/OSAtomic.h> to ensure that the master counter is handled correctly when several MBNetworkIndicator instances are in simultaneous use on multiple threads.

What’s Next

Our MBNetworkIndicator class is just one way to manage a shared resource while adhering to the principles of modularity.

In subsequent posts, we’ll discuss:


Please say hello to Lucene Sugar: a library that provides a more concise syntax for the Lucene API in the Scala language. Lucene Sugar makes it easier to:

  • compose Lucene indexes using the familiar Scala cake pattern
  • add indexed and/or stored fields to a Lucene document
  • index collections of documents
  • search! (You didn’t really expect that, did you?)

My general goal for Lucene Sugar is to turn some standard operations on their head. For example, instead of:

scala val doc = new Document doc.add(new StringField("string_field", "aString", Store.YES)) doc.add(new LongField("long_field", 123456L, Store.NO)) doc.add(new StoredField("int_field", 10))

you can now write:

scala val doc = new Document doc.addIndexedStoredField("string_field", "aString") doc.addIndexedOnlyField("long_field", 123456L) doc.addStoredOnlyField("int_field", 10)

Lucene Sugar is still in its infancy, but I believe it already offers great value to anyone wishing to use Lucene in Scala code.

Why I Created Sugar

Gilt’s inventory includes millions of different items in limited quantities. These items are sold quickly, which means that our inventory is constantly changing. A few weeks ago I found that I needed a data store capable of:

  • storing items composed of text and numbers
  • being indexed and filtered using extremely specific criteria (for example, all white shirts from Paul Smith that can be shipped to Canada)
  • working quickly and efficiently (a few 100ms per query)
  • being embeddable (I wanted the data management to be self-contained in the service without requiring any external dependencies

I’d used Lucene for other projects, and thought it might be a great fit for what I needed. In fact, it turned out that—despite its wordy API—Lucene works very well. To overcome the excess verbiage issue, I added some “Scala syntactic sugar” around the Lucene API to make it more concise and pleasant to use. After doing some coding, I realized that it could be helpful to convert this higher-level API into a library that could be reused in other projects. (I also badly wanted to publish my first open source Scala project, so this was a very good candidate.)

With Lucene Sugar, we can now build a search and browser service on top of our inventory data; the data is composed of textual attributes such as product name, brand, color and description as well as numeric data like price and size. I hope you find it useful as well!

Photo by Uwe Hermann. Creative Commons license.

The jQuery Foundation just posted video of “If You Love It So Much, Why Don’t You Write a Wrapper Around It?”—my presentation at last month’s jQuery Conference in Portland, Ore. In my talk, I focus on the importance of using consistent APIs and taking advantage of other people’s work (in the form of third-party code) when working with a large code base. Putting a wrapper around someone else’s code can give you the API and feature set you want, while saving you tons of tedious work writing business logic.

The last time I attended jQCon was in 2010, when it was held in Boston. The conference is sponsored by jQuery, and certainly features a fair amount of jQuery-related content, but one of the things I appreciate most about it is its focus on larger-scale, front-end issues of the day. This year was no exception.

Back in 2010, two major themes that emerged during jQCon were pubsub messaging and client-side templating. At that time, Gilt was somewhat behind the curve in these areas. Our front-end team came back from the conference feeling inspired and energized, and built systems to handle both pubsub messaging and client-side templating. One was Gilt.Notify, an adaptation of Peter Higgins’ pubsub plugin. The other system was Gilt.Template, which at the time was a template-engine-agnostic wrapper around client-side templating (since different teams were using different template engines). Both of these systems have evolved over time, as we’ve normalized to one template engine (Handlebars) and added private pubsub channels that function like observers, but both are still part of our new module-based front-end stack.

In 2013, we find ourselves right in line with the current state of the industry. Featured talks covered HTML5 polyfills, CSS3 animations, front-end unit testing, client-side MVC, promises, A/B testing, client-side build tools, and—as the topic of my presentation illustrates—wrapping third-party plugins and libraries. Gilt has been working on all the above over the past couple years, and it was good to know that we’re up-to-date with the latest in front-end technology.

Check out the slides here. If your window is large enough, you’ll see at the bottom the notes I wrote to accompany the slides.

It’s with great pleasure that we’re announcing the awesome Gilt API lessons on Codecademy!

Be ready to take your JavaScript skills to the next level and learn how to find the latest and most beautiful fashion products with the Gilt API.

Begin to learn our APIs now!

Join Gilt Groupe for the Hearst Fashion Hack, the largest fashion hackathon of the year, where you could win $10,000+ to launch your fashion app!

The Hearst Fashion Hack (#HearstFashionHack) kicks off on Saturday, February 9 at 9:00 a.m. with welcoming introductions by Hearst followed by developers pitching their ideas and forming teams. Coding begins promptly at 1:00 p.m. and submissions are due exactly 24 hours later. On Sunday, prototypes will be presented to the judges. Special consideration will be given to apps that inventively connect readers and editors in real-time.

Tickets are limited. We welcome enthusiasts from all levels of fashion expertise, from corporate juggernauts to prominent young students. We look forward to having you at the Hearst Fashion Hack and helping you build your fashion dreams.

The Gilt Public API is a great tool for developing new ways for people to shop quickly, efficiently, or on new platforms. But developers using the API are also finding unexpected things to do with Gilt data— they’re using it to make games.

So in the spirit of Friday, why not spend a few minutes playing with a couple of games that have been built on top of the Public API?

Gilt Memory was built by Karl Norling, a developer here at Gilt. See how quickly you can find the matching pairs of products, then challenge your friends to beat your score!

The Price is Right on Gilt was built overnight at the NYC Powered by MongoDB Hackathon last weekend. This live multiplayer game lets you and up to 3 other friends play a price-guessing game to see who knows Gilt’s products the best. Developer Yufei Liu built the project using Node.js and MongoDB.

Happy Friday, everyone!

What’s better than spending 24 hours in Manhattan hacking on sweet projects using MongoDB and the Gilt API? Doing it while supporting HackNY, a New York City organization that promotes innovation and entrepreneurship among the city’s up-and-coming students and hackers. And that’s exactly what you can do next weekend, April 27-28, at 10gen’s MongoDB Hackathon. A lot of great people, and great companies, are going to be there, and we’re excited to see you come down and make the next cool project. On Saturday night an esteemed panel of judges will choose winning projects and award all manner of prizes, including iPads, Xbox 360s, and more.

We’ll be at the event to share how to get started with the Public API and answer any questions you may have, give you ideas on what you could build, and maybe give you a sneak peek into what we’re working on for the future of the API, so come find us!

For questions about the event, you can send a tweet to @MongoDB. For questions about the API, get in touch @GiltTech or send an email to!

There’s been even more work done getting the Gilt API wrapped up in language bindings over the past two weeks and I’m here to present the newest to you in case any of them tickle your fancy.

gilt_api_php is a PHP client written by Gilt Tech member Dan Revel. This library has tests and a demo app to get you started on downloading and featuring sales and products in no time.

Gilt-Java, by Gilt Tech’s very own Nitin Dhar, is of course a Java library for the Public API. Nitin is working on some Android compatibility so mobile app developers don’t need to remain glued to our iOS bindings!

gilt-python is a brand new Python library brewed here at Gilt by engineer Andrew Ellerton. If you’re working in Python, give it a try and see how you like it!

We’re hard at work on compiling a permanent directory of client libraries like the ones we’ve featured on this blog and some of the applications people have built already. Email us soon if you have something you want to see included!

It’s been great to hear from developers over the past two weeks about their plans for the Gilt Public API, and we can only imagine what’s in the works out there that we haven’t heard about yet! Meanwhile, back at Gilt HQ, we’re hard at work on adding more to the API— more data and more ways of accessing what you want in the easiest way possible.

In the meantime, though, I’m happy to announce that we’ve finally got everything in place to enable you to participate in the affiliate marketing program. By enrolling in this program and adding a single parameter to all the requests you pass in, you can earn a competitive 6% commission on all sales from referred customers. When you consider that the luxury items on Gilt lead to average total order values of $150, that adds up pretty quickly.

All the information you need to get started has been added to the Gilt Developer Portal; the technical information is on the main documentation page and information about how to sign up for the affiliate program is available on our FAQ. What are you waiting for?