• Stars
    star
    136
  • Rank 266,732 (Top 6 %)
  • Language
    Java
  • License
    Apache License 2.0
  • Created over 9 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Java library for working with Guava futures

Futures-extra

Futures-extra is a set of small utility functions to simplify working with Guava's ListenableFuture class

Build status

Travis Coverage Status

Maven central

Maven Central

Build dependencies

  • Java 8 or higher
  • Maven

Runtime dependencies

  • Java 8 or higher
  • Guava 21.0 or higher
  • Google api-common from com.google.api

Usage

Futures-extra is meant to be used as a library embedded in other software. To import it with maven, use this:

<dependency>
  <groupId>com.spotify</groupId>
  <artifactId>futures-extra</artifactId>
  <version>4.2.0</version>
</dependency>

Examples

Joining multiple futures

A common use case is waiting for two or more futures and then transforming the result to something else. You can do this in a couple of different ways, here are two of them:

final ListenableFuture<A> futureA = getFutureA();
final ListenableFuture<B> futureB = getFutureB();

ListenableFuture<C> ret = Futures.transform(Futures.allAsList(futureA, futureB),
    (Function<List<?>, C>)list -> combine((A) list.get(0), (B) list.get(1), executor);

where combine is a method with parameters of type A and B returning C.

This one has the problem that you have to manually make sure that the casts and ordering are correct, otherwise you will get ClassCastException.

You could also access the futures directly to avoid casts:

final ListenableFuture<A> futureA = getFutureA();
final ListenableFuture<B> futureB = getFutureB();

ListenableFuture<C> ret = Futures.transform(Futures.allAsList(futureA, futureB),
    (Function<List<?>, C>)list -> combine(Futures.getUnchecked(futureA), Futures.getUnchecked(futureB), executor);

Now you instead need to make sure that the futures in the transform input are the same as the ones you getUnchecked. If you fail to do this, things may work anyway (which is a good way of hiding bugs), but block the thread, actually removing the asynchronous advantage. Even worse - the future may never finish, blocking the thread forever.

To simplify these use cases we have a couple of helper functions:

final ListenableFuture<A> futureA = getFutureA();
final ListenableFuture<B> futureB = getFutureB();

ListenableFuture<C> ret = FuturesExtra.syncTransform2(futureA, futureB,
    (a, b) -> combine(a, b), executor);

This is much clearer! We don't need any type information because the lambda can infer it, and we avoid the potential bugs that can occur as a result of the first to examples.

The tuple transform can be used up to 6 arguments named syncTransform2() through syncTransform6(). If you need more than that you could probably benefit from some refactoring, but you can also use FuturesExtra.join():

final ListenableFuture<A> futureA = getFutureA();
final ListenableFuture<B> futureB = getFutureB();

final ListenableFuture<JoinedResults> futureJoined = FuturesExtra.join(executor, futureA, futureB);
return Futures.transform(futureJoined,
    joined -> combine(joined.get(futureA), joined.get(futureB)), executor);

This supports an arbitrary number of futures, but is slightly more complex. However, it is much safer than the first two examples, because joined.get(...) will fail if you try to get the value of a future that was not part of the input.

Timeouts

Sometimes you want to stop waiting for a future after a specific timeout and to do this you generally need to have some sort of scheduling involved. To simplify that, you can use this:

final ListenableFuture<A> future = getFuture();
final ListenableFuture<A> futureWithTimeout = FuturesExtra.makeTimeoutFuture(scheduledExecutor, future, 100, TimeUnit.MILLISECONDS);

Select

If you have some futures and want to succeed as soon as the first one succeeds, you can use select:

final List<ListenableFuture<A>> futures = getFutures();
final ListenableFuture<A> firstSuccessful = FuturesExtra.select(futures, executor);

Success/Failure callbacks

You can attach callbacks that are run depending on the results of a future:

final ListenableFuture<A> future = getFuture();
FuturesExtra.addCallback(future, System.out::println, Throwable::printStackTrace, executor);

Alternatively, if you are only interested in either successful or failed results of a future, you can use:

final ListenableFuture<A> future = getFuture();
FuturesExtra.addSuccessCallback(future, System.out::println, executor);
final ListenableFuture<B> future = getFuture();
FuturesExtra.addFailureCallback(future, System.out::println, executor);

Concurrency limiting

If you want to fire of a large number of asynchronous requests or jobs, it can be useful to limit how many will run concurrently. To help with this, there is a new class called ConcurrencyLimiter. You use it like this:

int maxConcurrency = 10;
int maxQueueSize = 100;
ConcurrencyLimiter<T> limiter = ConcurrencyLimiter.create(maxConcurrency, maxQueueSize);
for (int i = 0; i < 1000; i++) {
  ListenableFuture<T> future = limiter.add(() -> createFuture());
}

The concurrency limiter will ensure that at most 10 futures are created and incomplete at the same time. All the jobs that are passed into ConcurrencyLimiter.add() will wait in a queue until the concurrency is below the limit.

The jobs you pass in should not be blocking or be overly CPU intensive. If that is something you need you should let your ConcurrencyLimiter jobs push the work on a thread pool.

The internal queue is bounded and if its limit is reached it, the call to add will return a failed future of ConcurrencyLimiter.CapacityReachedException.

Completed futures

In some cases you want to extract the value (or exception) from the future and you know that the future is completed so it won't be a blocking operation.

You could use these methods for that, but they will also block if the future is not complete which may lead to hard to find bugs.

T value = future.get();
T value = Futures.getUnchecked(future);

Instead you can use these methods which will never block but instead immediately throw an exception if the future is not completed. This is typically useful in unit tests (where futures should be immediate) and in general future callbacks/transforms where you know that a specific future must be completed for this codepath to be triggered.

T value = FuturesExtra.getCompleted(future);
Throwable exc = FuturesExtra.getException(future);

JDK 8 CompletableFuture <-> ListenableFuture Conversion

  • From ListenableFuture To JDK 8 CompletableFuture
ListenableFuture<V> listenable = getFuture();
CompletableFuture<V> completable = ListenableFuturesExtra.toCompletableFuture(listenable);
  • From JDK 8 CompletableFuture To ListenableFuture
CompletableFuture<V> completable = getFuture();
ListenableFuture<V> listenable = CompletableFuturesExtra.toListenableFuture(completable);
ApiFuture<V> apiFuture = getFuture();
CompletableFuture<V> completable = ApiFuturesExtra.toCompletableFuture(apiFuture);
CompletableFuture<V> completable = getFuture();
ApiFuture<V> apiFuture = CompletableFuturesExtra.toApiFuture(completable);

Ownership

The Weaver squad is currently owning this project internally. We are currently in the evaluating process of the ownership of this and other OSS Java libraries. The ownership takes into account ONLY security maintenance.

This repo is also co-owned by other people:

More Repositories

1

luigi

Luigi is a Python module that helps you build complex pipelines of batch jobs. It handles dependency resolution, workflow management, visualization etc. It also comes with Hadoop support built in.
Python
17,581
star
2

annoy

Approximate Nearest Neighbors in C++/Python optimized for memory usage and loading/saving to disk
C++
12,982
star
3

pedalboard

๐ŸŽ› ๐Ÿ”Š A Python library for audio.
C++
5,147
star
4

docker-gc

INACTIVE: Docker garbage collection of containers and images
Shell
5,068
star
5

chartify

Python library that makes it easy for data scientists to create charts.
Python
3,510
star
6

basic-pitch

A lightweight yet powerful audio-to-MIDI converter with pitch bend detection
Python
3,184
star
7

dockerfile-maven

MATURE: A set of Maven tools for dealing with Dockerfiles
Java
2,748
star
8

docker-maven-plugin

INACTIVE: A maven plugin for Docker
Java
2,652
star
9

scio

A Scala API for Apache Beam and Google Cloud Dataflow.
Scala
2,485
star
10

helios

Docker container orchestration platform
Java
2,097
star
11

web-api-examples

Basic examples to authenticate and fetch data using the Spotify Web API
HTML
1,889
star
12

HubFramework

DEPRECATED โ€“ Spotifyโ€™s component-driven UI framework for iOS
Objective-C
1,861
star
13

apollo

Java libraries for writing composable microservices
Java
1,648
star
14

dh-virtualenv

Python virtualenvs in Debian packages
Python
1,608
star
15

docker-client

INACTIVE: A simple docker client for the JVM
Java
1,429
star
16

docker-kafka

Kafka (and Zookeeper) in Docker
Shell
1,399
star
17

SPTPersistentCache

Everyone tries to implement a cache at some point in their iOS appโ€™s lifecycle, and this is ours.
Objective-C
1,243
star
18

voyager

๐Ÿ›ฐ๏ธ An approximate nearest-neighbor search library for Python and Java with a focus on ease of use, simplicity, and deployability.
C++
1,242
star
19

mobius

A functional reactive framework for managing state evolution and side-effects.
Java
1,223
star
20

sparkey

Simple constant key/value storage library, for read-heavy systems with infrequent large bulk inserts.
C
1,153
star
21

ruler

Gradle plugin which helps you analyze the size of your Android apps.
Kotlin
1,130
star
22

XCMetrics

XCMetrics is the easiest way to collect Xcode build metrics and improve developer productivity.
Swift
1,102
star
23

web-api

This issue tracker is no longer used. Join us in the Spotify for Developers forum for support with the Spotify Web API โžก๏ธ https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
RAML
981
star
24

echoprint-codegen

Codegen for Echoprint
C++
948
star
25

snakebite

A pure python HDFS client
Python
858
star
26

heroic

The Heroic Time Series Database
Java
843
star
27

klio

Smarter data pipelines for audio.
Python
836
star
28

XCRemoteCache

Swift
830
star
29

ios-sdk

Spotify SDK for iOS
Objective-C
643
star
30

SPTDataLoader

The HTTP library used by the Spotify iOS client
Objective-C
629
star
31

apps-tutorial

A Spotify App that contains working examples of the use of Spotify Apps API
628
star
32

JniHelpers

Tools for writing great JNI code
C++
590
star
33

postgresql-metrics

Tool that extracts and provides metrics on your PostgreSQL database
Python
588
star
34

Mobius.swift

A functional reactive framework for managing state evolution and side-effects [Swift implementation]
Swift
557
star
35

reactochart

๐Ÿ“ˆ React chart component library ๐Ÿ“‰
JavaScript
552
star
36

dockerfile-mode

An emacs mode for handling Dockerfiles
Emacs Lisp
537
star
37

threaddump-analyzer

A JVM threaddump analyzer
JavaScript
488
star
38

featran

A Scala feature transformation library for data science and machine learning
Scala
467
star
39

android-sdk

Spotify SDK for Android
HTML
457
star
40

echoprint-server

Server for the Echoprint audio fingerprint system
Java
395
star
41

completable-futures

Utilities for working with futures in Java 8
Java
385
star
42

web-scripts

DEPRECATED: A collection of base configs and CLI wrappers used to speed up development @ Spotify.
TypeScript
383
star
43

spotify-web-api-ts-sdk

A Typescript SDK for the Spotify Web API with types for returned data.
TypeScript
356
star
44

SpotifyLogin

Swift framework for authenticating with the Spotify API
Swift
347
star
45

ratatool

A tool for data sampling, data generation, and data diffing
Scala
338
star
46

fmt-maven-plugin

Opinionated Maven Plugin that formats your Java code.
Java
324
star
47

big-data-rosetta-code

Code snippets for solving common big data problems in various platforms. Inspired by Rosetta Code
Scala
287
star
48

trickle

A small library for composing asynchronous code
Java
285
star
49

coordinator

A visual interface for turning an SVG into XY coรถrdinates.
HTML
284
star
50

pythonflow

๐Ÿ Dataflow programming for python.
Python
283
star
51

styx

"The path to execution", Styx is a service that schedules batch data processing jobs in Docker containers on Kubernetes.
Java
266
star
52

cstar

Apache Cassandra cluster orchestration tool for the command line
Python
254
star
53

confidence

Python
254
star
54

netty-zmtp

A Netty implementation of ZMTP, the ZeroMQ Message Transport Protocol.
Java
242
star
55

ios-style

Guidelines for iOS development in use at Spotify
241
star
56

cassandra-reaper

Software to run automated repairs of cassandra
235
star
57

docker-cassandra

Cassandra in Docker with fast startup
Shell
220
star
58

basic-pitch-ts

A lightweight yet powerful audio-to-MIDI converter with pitch bend detection.
TypeScript
216
star
59

terraform-gke-kubeflow-cluster

Terraform module for creating GKE clusters to run Kubeflow
HCL
213
star
60

linux

Spotify's Linux kernel for Debian-based systems
C
206
star
61

dns-java

DNS wrapper library that provides SRV lookup functionality
Java
205
star
62

git-test

test your commits
Shell
203
star
63

SPStackedNav

[DEPRECATED] Navigation controller which represents its content in stacks of panes, rather than one at a time
Objective-C
195
star
64

spotify-json

Fast and nice to use C++ JSON library.
C++
194
star
65

quickstart

A CommonJS module resolver, loader and compiler for node.js and browsers.
JavaScript
193
star
66

dbeam

DBeam exports SQL tables into Avro files using JDBC and Apache Beam
Java
189
star
67

flink-on-k8s-operator

Kubernetes operator for managing the lifecycle of Apache Flink and Beam applications.
Go
185
star
68

bazel-tools

Tools for dealing with very large Bazel-managed repositories
Java
165
star
69

magnolify

A collection of Magnolia add-on modules
Scala
163
star
70

dataenum

Algebraic data types in Java.
Java
163
star
71

lingon

A user friendly tool for building single-page JavaScript applications
JavaScript
162
star
72

async-google-pubsub-client

[SUNSET] Async Google Pubsub Client
Java
157
star
73

gcp-audit

A tool for auditing security properties of GCP projects.
Python
157
star
74

spark-bigquery

Google BigQuery support for Spark, SQL, and DataFrames
Scala
155
star
75

should-up

Remove most of the "should" noise from your tests
JavaScript
153
star
76

folsom

An asynchronous memcache client for Java
Java
147
star
77

flo

A lightweight workflow definition library
Java
146
star
78

missinglink

Build time tool for detecting link problems in java projects
Java
144
star
79

android-auth

Spotify authentication and authorization for Android. Part of the Spotify Android SDK.
HTML
143
star
80

proto-registry

An implementation of the Protobuf Registry API
TypeScript
141
star
81

zoltar

Common library for serving TensorFlow, XGBoost and scikit-learn models in production.
Java
138
star
82

annoy-java

Approximate nearest neighbors in Java
Java
137
star
83

spotify-web-playback-sdk-example

React based example app that creates a new player in Spotify Connect to play music from in the browse using Spotify Web Playback SDK.
JavaScript
136
star
84

spydra

Ephemeral Hadoop clusters using Google Compute Platform
Java
134
star
85

docker-stress

Simple docker stress test and monitoring tools
Python
125
star
86

spotify-tensorflow

Provides Spotify-specific TensorFlow helpers
Python
124
star
87

github-java-client

A Java client to Github API
Java
120
star
88

crtauth

a public key backed client/server authentication system
Python
118
star
89

redux-location-state

Utilities for reading & writing Redux store state to & from the URL
JavaScript
118
star
90

sparkey-java

Java implementation of the Sparkey key value store
Java
117
star
91

realbook

Easier audio-based machine learning with TensorFlow.
Python
112
star
92

rspec-dns

Easily test your DNS with RSpec
Ruby
107
star
93

web-playback-sdk

This issue tracker is no longer used. Join us in the Spotify for Developers forum for support with the Spotify Web Playback SDK โžก๏ธ https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
107
star
94

ffwd-ruby

An event and metrics fast-forwarding agent.
Ruby
105
star
95

gimme

Creating time bound IAM Conditions with ease and flair
Python
103
star
96

super-smash-brogp

Sends and withdraws BGP prefixes for fun.
Python
98
star
97

spotify.github.io

Showcase site for hand-picked open-source projects by Spotify
HTML
96
star
98

lighthouse-audit-service

TypeScript
95
star
99

python-graphwalker

Python re-implementation of the graphwalker testing tool
Python
93
star
100

noether

Scala Aggregators used for ML Model metrics monitoring
Scala
91
star