spotify / trickle

A small library for composing asynchronous code

trickle

A small library for composing asynchronous code. The main reason for it to exist is to make it easier to create graphs of interconnected asynchronous calls, pushing the 'worrying about concurrency' aspects into the framework rather than mixing it in with the business logic.

NOTE: this project is no longer supported. Feel free to fork it if you like it. Internally, we've switched to using CompletionStage/CompletableFuture instead.

When should I use it?

• When you are combining more than 2 asynchronous calls together, and you think the code is hard to read.
• When you want to separate concurrency management aspects (when code does something) from business logic (what it does).
• When you want to use something smaller and easier to learn than frameworks like Akka and RxJava.

Probably none of the above, see note at top.

Getting Started

Include the latest version of Trickle into your project:

<dependency>
  <groupId>com.spotify</groupId>
  <artifactId>trickle</artifactId>
  <version>0.6.2</version>
</dependency>

Define the input parameters to your call graph:

public static final Input<String> KEYWORD = Input.named("keyword");
public static final Input<String> ARTIST = Input.named("artist");

Define the code to be executed in the nodes of your graph:

Func1<String, List<Track>> findTracks = new Func1<String, List<Track>>() {
  @Override
  public ListenableFuture<List<Track>> run(String keyword) {
    return search.findTracks(keyword);
  }
};
Func1<String, Artist> findArtist = new Func1<String, Artist>() {
  @Override
  public ListenableFuture<Artist> run(String artistName) {
    return metadata.lookupArtist(artistName);
  }
};
Func2<Artist, List<Track>, MyOutput> combine = new Func2<Artist, List<Track>, MyOutput>() {
  @Override
  public ListenableFuture<MyOutput> run(Artist artist, List<Track> tracks) {
    return Futures.immediateFuture(new MyOutput(artist, tracks));
  }
};

Wire up your call graph:

Graph<List<Track>> tracks = Trickle.call(findTracks).with(KEYWORD).fallback(emptyList());
Graph<Artist> artist = Trickle.call(findArtist).with(ARTIST);
this.output = Trickle.call(combine).with(artist, tracks);

Note that the findTracks node has been given a fallback, so an empty list of tracks will be used if the call to find tracks throws an exception. This way, you can get graceful degradation in case of partial failure.

At some later stage, call the graph for some specific keyword and artist name:

public ListenableFuture<MyOutput> doTheThing(String keyword, String artistName) {
  return this.output.bind(KEYWORD, keyword).bind(ARTIST, artistName).run();
}

See Examples.java for more examples and see the wiki for more in-depth descriptions of the library.

Notes about maturity

We're using Trickle internally at Spotify in core, production-critical services that would break Spotify completely if they failed. This means we have a fairly high degree of confidence that it works. It is, however, a young library and you shouldn't be surprised if there are API changes in the next few months.

Code of conduct

This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.

trickle's Issues

Create example based on playlistdecorator from user-profile-view and maybe nameless-registry

Clean up some protobuf stuff, and show an example of what real Spotify code using Trickle looks like.

Graph name is confusing

Specifically, there are issues around:

• the Trickle.call().with() sequence which creates a node but returns a graph.
• the fact that with() takes Graphs as parameters, but of course an edge in a graph goes from one node to another, not from a node to another graph.

Documentation executor required

Their seems to some obvious lack executor service documention whereas guava docs do say that is allowed? I could not even find any trickle test that do take in executor service. Is that not required

Pass the exception to next node

Sometimes，only the fallback object is not enough， the next node need to know which exception happened to determine which action should do.

Formalise contract of NodeInfo with unit tests

Things like object identities, etc., should be clearer. That is, how can you use the NodeInfo things to traverse a Graph and extract information about it? That will require things like ensuring that when NodeInfo for the same object is extracted from two different paths in the graph, the object will have the same identity as defined by equals/hashCode, etc.

Update usage instructions in README until artifacts are in Maven central

Submit version 0.6.1 to Maven central

Hi

It would be great if this version could be submitted if you are ready to release it.

Thank you

Mik

Publish on sonatype/Maven central

Create wiki pages