annoy-rb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06af1da176d1d25ba1d0058a34d21483413deff690004d9e3dd5471c9d9f4294
-  data.tar.gz: 98eab997b5d6b2439c7a2b3ab26a25818428bb6fcc0811447a903c3a83decfab
+  metadata.gz: a8884d4c472560181032959b32eb3396b698dedc7dac7211af67bdb03aaa90f6
+  data.tar.gz: 1eb4acf66b0685e06aed6455c4efd0ffcb17f8805e9b619f003fb62046db41db
 SHA512:
-  metadata.gz: 054df371bf5596ebe6a59d003c5c483d1b4ba885ad55fcd1e0232d6a3d52ad0650e4d6f24805737123ca68350789b7cded0a9e58aafabb94cfa31ed5f813619b
-  data.tar.gz: 9b22bf40a94e081a39249f1068d32cfa0b4112f951f0172a9004a887ab2b7ebe460b6baa4bbd904906928c1571257cb0e277e59adf6d21e5df61c842759d46df
+  metadata.gz: 0103da7a9f443c4fed168ac61004aa135bbd534edaff6f20d641ef818348288a851370693d75657794c8ebfe9dd45dd54177315c7ac68a3400e43c87dfb1c4bb
+  data.tar.gz: 8e7314fbee4ed318c47848941aba40f6363f350181c616045354af696dc99cbd678c7b999b5bfa35339ad82e6cb3f6782510354d44db5d4d1fb81591128f4822

data/.github/workflows/build.yml

@@ -0,0 +1,22 @@
+name: build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ '2.6', '2.7', '3.0' ]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set upt Ruby ${{ matrix.ruby }}
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: Build and test with Rake
+        run: |
+          gem install --no-document bundler
+          bundle install --jobs 4 --retry 3
+          bundle exec rake

data/CHANGELOG.md

@@ -1,2 +1,21 @@
+## 0.3.0
+- Add type declaration file: sig/annoy.rbs
+- Fix get_distance method to return integer typed value on hamming metric index.
+- Rename native extension files.
+
+## 0.2.3
+- Add GC guard to index saving and loading methods.
+
+## 0.2.2
+- Replace Data_ functions to TypedData_ functions.
+
+## 0.2.1
+- Fix to free char array of error message before calling rb_raise.
+- Fix to use array allocated with ruby_xmalloc instead of vector class in C++.
+
+## 0.2.0
+- Update bundled Annoy version to 1.17.0.
+- Support multithreaded index building.
+
 ## 0.1.0
 - First release.

data/Gemfile

@@ -1,8 +1,10 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in annoy.gemspec
 gemspec
 
-gem "rake", "~> 12.0"
-gem "rake-compiler"
-gem "rspec", "~> 3.0"
+gem 'rake', '~> 13.0'
+gem 'rake-compiler', '~> 1.1'
+gem 'rspec', '~> 3.0'
+gem 'rbs', '~> 1.2'
+gem 'steep', '~> 0.44'

data/README.md

@@ -1,8 +1,9 @@
 # Annoy.rb
 
-[![Build Status](https://travis-ci.org/yoshoku/annoy.rb.svg?branch=master)](https://travis-ci.org/yoshoku/annoy.rb)
+[![Build Status](https://github.com/yoshoku/annoy.rb/workflows/build/badge.svg)](https://github.com/yoshoku/annoy.rb/actions?query=workflow%3Abuild)
 [![Gem Version](https://badge.fury.io/rb/annoy-rb.svg)](https://badge.fury.io/rb/annoy-rb)
-[![License](https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg)](https://github.com/yoshoku/annoy.rb/blob/master/LICENSE.txt)
+[![License](https://img.shields.io/badge/License-Apache%202.0-yellowgreen.svg)](https://github.com/yoshoku/annoy.rb/blob/main/LICENSE.txt)
+[![Documentation](http://img.shields.io/badge/api-reference-blue.svg)](https://yoshoku.github.io/annoy.rb/doc/)
 
 Annoy.rb is a Ruby binding for the [Annoy (Approximate Nearest Neighbors Oh Yeah)](https://github.com/spotify/annoy).
 
@@ -24,6 +25,10 @@ Or install it yourself as:
 
 Note: Annoy.rb does not require the installation of another external library.
 
+## Documentation
+
+* [Annoy.rb API Documentation](https://yoshoku.github.io/annoy.rb/doc/)
+
 ## Usage
 
 ```ruby
@@ -51,8 +56,8 @@ The gem is available as open source under the terms of the [Apache-2.0 License](
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/yoshoku/annoy.rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/yoshoku/annoy.rb/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/yoshoku/annoy.rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/yoshoku/annoy.rb/blob/main/CODE_OF_CONDUCT.md).
 
 ## Code of Conduct
 
-Everyone interacting in the Annoy.rb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yoshoku/annoy.rb/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Annoy.rb project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/yoshoku/annoy.rb/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -7,7 +7,8 @@ require 'rake/extensiontask'
 
 task :build => :compile
 
-Rake::ExtensionTask.new('annoy') do |ext|
+Rake::ExtensionTask.new('annoyext') do |ext|
+  ext.ext_dir = 'ext/annoy'
   ext.lib_dir = 'lib/annoy'
 end
 

data/Steepfile

@@ -0,0 +1,20 @@
+target :lib do
+  signature "sig"
+
+  check "lib"                       # Directory name
+#   check "Gemfile"                   # File name
+#   check "app/models/**/*.rb"        # Glob
+#   # ignore "lib/templates/*.rb"
+#
+#   # library "pathname", "set"       # Standard libraries
+#   # library "strong_json"           # Gems
+end
+
+# target :spec do
+#   signature "sig", "sig-private"
+#
+#   check "spec"
+#
+#   # library "pathname", "set"       # Standard libraries
+#   # library "rspec"
+# end

data/annoy-rb.gemspec

@@ -13,7 +13,8 @@ Gem::Specification.new do |spec|
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
-  spec.metadata['changelog_uri'] = 'https://github.com/yoshoku/annoy.rb/blob/master/CHANGELOG.md'
+  spec.metadata['changelog_uri'] = 'https://github.com/yoshoku/annoy.rb/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://yoshoku.github.io/annoy.rb/doc/'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

data/ext/annoy/{annoy.cpp → annoyext.cpp}

@@ -16,15 +16,15 @@
  * limitations under the License.
  */
 
-#include "annoy.hpp"
+#include "annoyext.hpp"
 
 extern "C"
-void Init_annoy(void)
+void Init_annoyext(void)
 {
   VALUE rb_mAnnoy = rb_define_module("Annoy");
-  VALUE rb_cAnnoyIndexAngular = RbAnnoyIndex<AnnoyIndexAngular, double>::define_class(rb_mAnnoy, "AnnoyIndexAngular");
-  VALUE rb_cAnnoyIndexDotProduct = RbAnnoyIndex<AnnoyIndexDotProduct, double>::define_class(rb_mAnnoy, "AnnoyIndexDotProduct");
-  VALUE rb_cAnnoyIndexHamming = RbAnnoyIndex<AnnoyIndexHamming, uint64_t>::define_class(rb_mAnnoy, "AnnoyIndexHamming");
-  VALUE rb_cAnnoyIndexEuclidean = RbAnnoyIndex<AnnoyIndexEuclidean, double>::define_class(rb_mAnnoy, "AnnoyIndexEuclidean");
-  VALUE rb_cAnnoyIndexManhattan = RbAnnoyIndex<AnnoyIndexManhattan, double>::define_class(rb_mAnnoy, "AnnoyIndexManhattan");
+  RbAnnoyIndex<AnnoyIndexAngular, double>::define_class(rb_mAnnoy, "AnnoyIndexAngular");
+  RbAnnoyIndex<AnnoyIndexDotProduct, double>::define_class(rb_mAnnoy, "AnnoyIndexDotProduct");
+  RbAnnoyIndex<AnnoyIndexHamming, uint64_t>::define_class(rb_mAnnoy, "AnnoyIndexHamming");
+  RbAnnoyIndex<AnnoyIndexEuclidean, double>::define_class(rb_mAnnoy, "AnnoyIndexEuclidean");
+  RbAnnoyIndex<AnnoyIndexManhattan, double>::define_class(rb_mAnnoy, "AnnoyIndexManhattan");
 }

data/ext/annoy/{annoy.hpp → annoyext.hpp}

@@ -16,8 +16,8 @@
  * limitations under the License.
  */
 
-#ifndef ANNOY_HPP
-#define ANNOY_HPP 1
+#ifndef ANNOYEXT_HPP
+#define ANNOYEXT_HPP 1
 
 #include <typeinfo>
 
@@ -25,28 +25,38 @@
 #include <annoylib.h>
 #include <kissrandom.h>
 
-typedef AnnoyIndex<int, double, Angular, Kiss64Random> AnnoyIndexAngular;
-typedef AnnoyIndex<int, double, DotProduct, Kiss64Random> AnnoyIndexDotProduct;
-typedef AnnoyIndex<int, uint64_t, Hamming, Kiss64Random> AnnoyIndexHamming;
-typedef AnnoyIndex<int, double, Euclidean, Kiss64Random> AnnoyIndexEuclidean;
-typedef AnnoyIndex<int, double, Manhattan, Kiss64Random> AnnoyIndexManhattan;
+#ifdef ANNOYLIB_MULTITHREADED_BUILD
+  typedef AnnoyIndexMultiThreadedBuildPolicy AnnoyIndexThreadedBuildPolicy;
+#else
+  typedef AnnoyIndexSingleThreadedBuildPolicy AnnoyIndexThreadedBuildPolicy;
+#endif
+
+typedef AnnoyIndex<int, double, Angular, Kiss64Random, AnnoyIndexThreadedBuildPolicy> AnnoyIndexAngular;
+typedef AnnoyIndex<int, double, DotProduct, Kiss64Random, AnnoyIndexThreadedBuildPolicy> AnnoyIndexDotProduct;
+typedef AnnoyIndex<int, uint64_t, Hamming, Kiss64Random, AnnoyIndexThreadedBuildPolicy> AnnoyIndexHamming;
+typedef AnnoyIndex<int, double, Euclidean, Kiss64Random, AnnoyIndexThreadedBuildPolicy> AnnoyIndexEuclidean;
+typedef AnnoyIndex<int, double, Manhattan, Kiss64Random, AnnoyIndexThreadedBuildPolicy> AnnoyIndexManhattan;
 
 template<class T, typename F> class RbAnnoyIndex
 {
   public:
     static VALUE annoy_index_alloc(VALUE self) {
       T* ptr = (T*)ruby_xmalloc(sizeof(T));
-      return Data_Wrap_Struct(self, NULL, annoy_index_free, ptr);
+      return TypedData_Wrap_Struct(self, &annoy_index_type, ptr);
     };
 
-    static void annoy_index_free(T* ptr) {
-      ptr->~AnnoyIndex();
+    static void annoy_index_free(void* ptr) {
+      ((T*)ptr)->~AnnoyIndex();
       ruby_xfree(ptr);
     };
 
+    static size_t annoy_index_size(const void* ptr) {
+      return sizeof(*((T*)ptr));
+    };
+
     static T* get_annoy_index(VALUE self) {
       T* ptr;
-      Data_Get_Struct(self, T, ptr);
+      TypedData_Get_Struct(self, T, &annoy_index_type, ptr);
       return ptr;
     };
 
@@ -55,7 +65,7 @@ template<class T, typename F> class RbAnnoyIndex
       rb_define_alloc_func(rb_cAnnoyIndex, annoy_index_alloc);
       rb_define_method(rb_cAnnoyIndex, "initialize", RUBY_METHOD_FUNC(_annoy_index_init), 1);
       rb_define_method(rb_cAnnoyIndex, "add_item", RUBY_METHOD_FUNC(_annoy_index_add_item), 2);
-      rb_define_method(rb_cAnnoyIndex, "build", RUBY_METHOD_FUNC(_annoy_index_build), 1);
+      rb_define_method(rb_cAnnoyIndex, "build", RUBY_METHOD_FUNC(_annoy_index_build), 2);
       rb_define_method(rb_cAnnoyIndex, "save", RUBY_METHOD_FUNC(_annoy_index_save), 2);
       rb_define_method(rb_cAnnoyIndex, "load", RUBY_METHOD_FUNC(_annoy_index_load), 2);
       rb_define_method(rb_cAnnoyIndex, "unload", RUBY_METHOD_FUNC(_annoy_index_unload), 0);
@@ -73,6 +83,7 @@ template<class T, typename F> class RbAnnoyIndex
     };
 
   private:
+    static const rb_data_type_t annoy_index_type;
 
     static VALUE _annoy_index_init(VALUE self, VALUE _n_dims) {
       const int n_dims = NUM2INT(_n_dims);
@@ -95,31 +106,34 @@ template<class T, typename F> class RbAnnoyIndex
         return Qfalse;
       }
 
-      std::vector<F> vec(n_dims, 0);
+      F* vec = (F*)ruby_xmalloc(n_dims * sizeof(F));
       for (int i = 0; i < n_dims; i++) {
         vec[i] = typeid(F) == typeid(double) ? NUM2DBL(rb_ary_entry(arr, i)) : NUM2UINT(rb_ary_entry(arr, i));
       }
 
       char* error;
-      if (!get_annoy_index(self)->add_item(idx, &vec[0], &error)) {
-        rb_raise(rb_eRuntimeError, "%s", error);
+      if (!get_annoy_index(self)->add_item(idx, vec, &error)) {
+        VALUE error_str = rb_str_new_cstr(error);
         free(error);
+        ruby_xfree(vec);
+        rb_raise(rb_eRuntimeError, "%s", StringValuePtr(error_str));
         return Qfalse;
       }
 
+      ruby_xfree(vec);
       return Qtrue;
     };
 
-    static VALUE _annoy_index_build(VALUE self, VALUE _n_trees) {
+    static VALUE _annoy_index_build(VALUE self, VALUE _n_trees, VALUE _n_jobs) {
       const int n_trees = NUM2INT(_n_trees);
+      const int n_jobs = NUM2INT(_n_jobs);
       char* error;
-
-      if (!get_annoy_index(self)->build(n_trees, &error)) {
-        rb_raise(rb_eRuntimeError, "%s", error);
+      if (!get_annoy_index(self)->build(n_trees, n_jobs, &error)) {
+        VALUE error_str = rb_str_new_cstr(error);
         free(error);
+        rb_raise(rb_eRuntimeError, "%s", StringValuePtr(error_str));
         return Qfalse;
       }
-
       return Qtrue;
     };
 
@@ -127,13 +141,13 @@ template<class T, typename F> class RbAnnoyIndex
       const char* filename = StringValuePtr(_filename);
       const bool prefault = _prefault == Qtrue ? true : false;
       char* error;
-
       if (!get_annoy_index(self)->save(filename, prefault, &error)) {
-        rb_raise(rb_eRuntimeError, "%s", error);
+        VALUE error_str = rb_str_new_cstr(error);
         free(error);
+        rb_raise(rb_eRuntimeError, "%s", StringValuePtr(error_str));
         return Qfalse;
       }
-
+      RB_GC_GUARD(_filename);
       return Qtrue;
     };
 
@@ -141,13 +155,13 @@ template<class T, typename F> class RbAnnoyIndex
       const char* filename = StringValuePtr(_filename);
       const bool prefault = _prefault == Qtrue ? true : false;
       char* error;
-
       if (!get_annoy_index(self)->load(filename, prefault, &error)) {
-        rb_raise(rb_eRuntimeError, "%s", error);
+        VALUE error_str = rb_str_new_cstr(error);
         free(error);
+        rb_raise(rb_eRuntimeError, "%s", StringValuePtr(error_str));
         return Qfalse;
       }
-
+      RB_GC_GUARD(_filename);
       return Qtrue;
     };
 
@@ -201,7 +215,7 @@ template<class T, typename F> class RbAnnoyIndex
         return Qfalse;
       }
 
-      std::vector<F> vec(n_dims, 0);
+      F* vec = (F*)ruby_xmalloc(n_dims * sizeof(F));
       for (int i = 0; i < n_dims; i++) {
         vec[i] = typeid(F) == typeid(double) ? NUM2DBL(rb_ary_entry(_vec, i)) : NUM2UINT(rb_ary_entry(_vec, i));
       }
@@ -212,7 +226,9 @@ template<class T, typename F> class RbAnnoyIndex
       std::vector<int> neighbors;
       std::vector<F> distances;
 
-      get_annoy_index(self)->get_nns_by_vector(&vec[0], n_neighbors, search_k, &neighbors, include_distances ? &distances : NULL);
+      get_annoy_index(self)->get_nns_by_vector(vec, n_neighbors, search_k, &neighbors, include_distances ? &distances : NULL);
+
+      ruby_xfree(vec);
 
       const int sz_neighbors = neighbors.size();
       VALUE neighbors_arr = rb_ary_new2(sz_neighbors);
@@ -239,23 +255,24 @@ template<class T, typename F> class RbAnnoyIndex
     static VALUE _annoy_index_get_item(VALUE self, VALUE _idx) {
       const int idx = NUM2INT(_idx);
       const int n_dims = get_annoy_index(self)->get_f();
-      std::vector<F> vec(n_dims, 0);
+      F* vec = (F*)ruby_xmalloc(n_dims * sizeof(F));
       VALUE arr = rb_ary_new2(n_dims);
 
-      get_annoy_index(self)->get_item(idx, &vec[0]);
+      get_annoy_index(self)->get_item(idx, vec);
 
       for (int i = 0; i < n_dims; i++) {
         rb_ary_store(arr, i, typeid(F) == typeid(double) ? DBL2NUM(vec[i]) : UINT2NUM(vec[i]));
       }
 
+      ruby_xfree(vec);
       return arr;
     };
 
     static VALUE _annoy_index_get_distance(VALUE self, VALUE _i, VALUE _j) {
       const int i = NUM2INT(_i);
       const int j = NUM2INT(_j);
-      const double dist = get_annoy_index(self)->get_distance(i, j);
-      return DBL2NUM(dist);
+      const F dist = get_annoy_index(self)->get_distance(i, j);
+      return typeid(F) == typeid(double) ? DBL2NUM(dist) : UINT2NUM(dist);
     };
 
     static VALUE _annoy_index_get_n_items(VALUE self) {
@@ -272,10 +289,12 @@ template<class T, typename F> class RbAnnoyIndex
       const char* filename = StringValuePtr(_filename);
       char* error;
       if (!get_annoy_index(self)->on_disk_build(filename, &error)) {
-        rb_raise(rb_eRuntimeError, "%s", error);
+        VALUE error_str = rb_str_new_cstr(error);
         free(error);
+        rb_raise(rb_eRuntimeError, "%s", StringValuePtr(error_str));
         return Qfalse;
       }
+      RB_GC_GUARD(_filename);
       return Qtrue;
     };
 
@@ -297,4 +316,17 @@ template<class T, typename F> class RbAnnoyIndex
     };
 };
 
-#endif /* ANNOY_HPP */
+template<class T, typename F>
+const rb_data_type_t RbAnnoyIndex<T, F>::annoy_index_type = {
+  "RbAnnoyIndex",
+  {
+    NULL,
+    RbAnnoyIndex::annoy_index_free,
+    RbAnnoyIndex::annoy_index_size
+  },
+  NULL,
+  NULL,
+  RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+#endif /* ANNOYEXT_HPP */

data/ext/annoy/extconf.rb

@@ -2,8 +2,8 @@ require 'mkmf'
 
 abort 'libstdc++ is not found.' unless have_library('stdc++')
 
-$CXXFLAGS << " -march=native"
+$CXXFLAGS << " -std=c++14 -march=native -DANNOYLIB_MULTITHREADED_BUILD"
 $INCFLAGS << " -I$(srcdir)/src"
 $VPATH << "$(srcdir)/src"
 
-create_makefile('annoy/annoy')
+create_makefile('annoy/annoyext')

data/ext/annoy/src/annoylib.h

@@ -58,6 +58,12 @@ typedef signed __int64    int64_t;
 #include <queue>
 #include <limits>
 
+#ifdef ANNOYLIB_MULTITHREADED_BUILD
+#include <thread>
+#include <mutex>
+#include <shared_mutex>
+#endif
+
 #ifdef _MSC_VER
 // Needed for Visual Studio to disable runtime checks for mempcy
 #pragma runtime_checks("s", off)
@@ -104,7 +110,6 @@ inline void set_error_from_string(char **error, const char* msg) {
 #ifndef _MSC_VER
 #define popcount __builtin_popcountll
 #else // See #293, #358
-#define isnan(x) _isnan(x)
 #define popcount cole_popcount
 #endif
 
@@ -346,7 +351,7 @@ inline float euclidean_distance<float>(const float* x, const float* y, int f) {
 
 #endif
 
-
+ 
 template<typename T>
 inline T get_norm(T* v, int f) {
   return sqrt(dot(v, v, f));
@@ -358,7 +363,7 @@ inline void two_means(const vector<Node*>& nodes, int f, Random& random, bool co
     This algorithm is a huge heuristic. Empirically it works really well, but I
     can't motivate it well. The basic idea is to keep two centroids and assign
     points to either one of them. We weight each centroid by the number of points
-    assigned to it, so to balance it.
+    assigned to it, so to balance it. 
   */
   static int iteration_steps = 200;
   size_t count = nodes.size();
@@ -548,7 +553,7 @@ struct DotProduct : Angular {
   static inline void create_split(const vector<Node<S, T>*>& nodes, int f, size_t s, Random& random, Node<S, T>* n) {
     Node<S, T>* p = (Node<S, T>*)alloca(s);
     Node<S, T>* q = (Node<S, T>*)alloca(s);
-    DotProduct::zero_value(p);
+    DotProduct::zero_value(p); 
     DotProduct::zero_value(q);
     two_means<T, Random, DotProduct, Node<S, T> >(nodes, f, random, true, p, q);
     for (int z = 0; z < f; z++)
@@ -594,8 +599,8 @@ struct DotProduct : Angular {
     // Step one: compute the norm of each vector and store that in its extra dimension (f-1)
     for (S i = 0; i < node_count; i++) {
       Node* node = get_node_ptr<S, Node>(nodes, _s, i);
-      T norm = sqrt(dot(node->v, node->v, f));
-      if (isnan(norm)) norm = 0;
+      T d = dot(node->v, node->v, f);
+      T norm = d < 0 ? 0 : sqrt(d);
       node->dot_factor = norm;
     }
 
@@ -612,9 +617,8 @@ struct DotProduct : Angular {
     for (S i = 0; i < node_count; i++) {
       Node* node = get_node_ptr<S, Node>(nodes, _s, i);
       T node_norm = node->dot_factor;
-
-      T dot_factor = sqrt(pow(max_norm, static_cast<T>(2.0)) - pow(node_norm, static_cast<T>(2.0)));
-      if (isnan(dot_factor)) dot_factor = 0;
+      T squared_norm_diff = pow(max_norm, static_cast<T>(2.0)) - pow(node_norm, static_cast<T>(2.0));
+      T dot_factor = squared_norm_diff < 0 ? 0 : sqrt(squared_norm_diff);
 
       node->dot_factor = dot_factor;
     }
@@ -753,7 +757,7 @@ struct Minkowski : Base {
 struct Euclidean : Minkowski {
   template<typename S, typename T>
   static inline T distance(const Node<S, T>* x, const Node<S, T>* y, int f) {
-    return euclidean_distance(x->v, y->v, f);
+    return euclidean_distance(x->v, y->v, f);    
   }
   template<typename S, typename T, typename Random>
   static inline void create_split(const vector<Node<S, T>*>& nodes, int f, size_t s, Random& random, Node<S, T>* n) {
@@ -817,7 +821,7 @@ class AnnoyIndexInterface {
   // Note that the methods with an **error argument will allocate memory and write the pointer to that string if error is non-NULL
   virtual ~AnnoyIndexInterface() {};
   virtual bool add_item(S item, const T* w, char** error=NULL) = 0;
-  virtual bool build(int q, char** error=NULL) = 0;
+  virtual bool build(int q, int n_threads=-1, char** error=NULL) = 0;
   virtual bool unbuild(char** error=NULL) = 0;
   virtual bool save(const char* filename, bool prefault=false, char** error=NULL) = 0;
   virtual void unload() = 0;
@@ -833,7 +837,7 @@ class AnnoyIndexInterface {
   virtual bool on_disk_build(const char* filename, char** error=NULL) = 0;
 };
 
-template<typename S, typename T, typename Distance, typename Random>
+template<typename S, typename T, typename Distance, typename Random, class ThreadedBuildPolicy>
   class AnnoyIndex : public AnnoyIndexInterface<S, T> {
   /*
    * We use random projection to build a forest of binary trees of all items.
@@ -850,12 +854,13 @@ protected:
   const int _f;
   size_t _s;
   S _n_items;
-  Random _random;
   void* _nodes; // Could either be mmapped, or point to a memory buffer that we reallocate
   S _n_nodes;
   S _nodes_size;
   vector<S> _roots;
   S _K;
+  bool _is_seeded;
+  int _seed;
   bool _loaded;
   bool _verbose;
   int _fd;
@@ -863,7 +868,7 @@ protected:
   bool _built;
 public:
 
-   AnnoyIndex(int f) : _f(f), _random() {
+   AnnoyIndex(int f) : _f(f) {
     _s = offsetof(Node, v) + _f * sizeof(T); // Size of each node
     _verbose = false;
     _built = false;
@@ -907,7 +912,7 @@ public:
 
     return true;
   }
-
+    
   bool on_disk_build(const char* file, char** error=NULL) {
     _on_disk = true;
     _fd = open(file, O_RDWR | O_CREAT | O_TRUNC, (int) 0600);
@@ -928,8 +933,8 @@ public:
 #endif
     return true;
   }
-
-  bool build(int q, char** error=NULL) {
+    
+  bool build(int q, int n_threads=-1, char** error=NULL) {
     if (_loaded) {
       set_error_from_string(error, "You can't build a loaded index");
       return false;
@@ -943,21 +948,8 @@ public:
     D::template preprocess<T, S, Node>(_nodes, _s, _n_items, _f);
 
     _n_nodes = _n_items;
-    while (1) {
-      if (q == -1 && _n_nodes >= _n_items * 2)
-        break;
-      if (q != -1 && _roots.size() >= (size_t)q)
-        break;
-      if (_verbose) showUpdate("pass %zd...\n", _roots.size());
-
-      vector<S> indices;
-      for (S i = 0; i < _n_items; i++) {
-        if (_get(i)->n_descendants >= 1) // Issue #223
-          indices.push_back(i);
-      }
 
-      _roots.push_back(_make_tree(indices, true));
-    }
+    ThreadedBuildPolicy::template build<S, T>(this, q, n_threads);
 
     // Also, copy the roots into the last segment of the array
     // This way we can load them faster without reading the whole file
@@ -967,7 +959,7 @@ public:
     _n_nodes += _roots.size();
 
     if (_verbose) showUpdate("has %d nodes\n", _n_nodes);
-
+    
     if (_on_disk) {
       if (!remap_memory_and_truncate(&_nodes, _fd,
           static_cast<size_t>(_s) * static_cast<size_t>(_nodes_size),
@@ -981,7 +973,7 @@ public:
     _built = true;
     return true;
   }
-
+  
   bool unbuild(char** error=NULL) {
     if (_loaded) {
       set_error_from_string(error, "You can't unbuild a loaded index");
@@ -1035,6 +1027,7 @@ public:
     _n_nodes = 0;
     _nodes_size = 0;
     _on_disk = false;
+    _is_seeded = false;
     _roots.clear();
   }
 
@@ -1142,29 +1135,82 @@ public:
   }
 
   void set_seed(int seed) {
+    _is_seeded = true;
+    _seed = seed;
+  }
+
+  void thread_build(int q, int thread_idx, ThreadedBuildPolicy& threaded_build_policy) {
+    Random _random;
+    // Each thread needs its own seed, otherwise each thread would be building the same tree(s)
+    int seed = _is_seeded ? _seed + thread_idx : thread_idx;
     _random.set_seed(seed);
+
+    vector<S> thread_roots;
+    while (1) {
+      if (q == -1) {
+        threaded_build_policy.lock_n_nodes();
+        if (_n_nodes >= 2 * _n_items) {
+          threaded_build_policy.unlock_n_nodes();
+          break;
+        }
+        threaded_build_policy.unlock_n_nodes();
+      } else {
+        if (thread_roots.size() >= (size_t)q) {
+          break;
+        }
+      }
+
+      if (_verbose) showUpdate("pass %zd...\n", thread_roots.size());
+
+      vector<S> indices;
+      threaded_build_policy.lock_shared_nodes();
+      for (S i = 0; i < _n_items; i++) {
+        if (_get(i)->n_descendants >= 1) { // Issue #223
+          indices.push_back(i);
+        }
+      }
+      threaded_build_policy.unlock_shared_nodes();
+
+      thread_roots.push_back(_make_tree(indices, true, _random, threaded_build_policy));
+    }
+
+    threaded_build_policy.lock_roots();
+    _roots.insert(_roots.end(), thread_roots.begin(), thread_roots.end());
+    threaded_build_policy.unlock_roots();
   }
 
 protected:
-  void _allocate_size(S n) {
+  void _reallocate_nodes(S n) {
+    const double reallocation_factor = 1.3;
+    S new_nodes_size = std::max(n, (S) ((_nodes_size + 1) * reallocation_factor));
+    void *old = _nodes;
+    
+    if (_on_disk) {
+      if (!remap_memory_and_truncate(&_nodes, _fd, 
+          static_cast<size_t>(_s) * static_cast<size_t>(_nodes_size), 
+          static_cast<size_t>(_s) * static_cast<size_t>(new_nodes_size)) && 
+          _verbose)
+          showUpdate("File truncation error\n");
+    } else {
+      _nodes = realloc(_nodes, _s * new_nodes_size);
+      memset((char *) _nodes + (_nodes_size * _s) / sizeof(char), 0, (new_nodes_size - _nodes_size) * _s);
+    }
+    
+    _nodes_size = new_nodes_size;
+    if (_verbose) showUpdate("Reallocating to %d nodes: old_address=%p, new_address=%p\n", new_nodes_size, old, _nodes);
+  }
+
+  void _allocate_size(S n, ThreadedBuildPolicy& threaded_build_policy) {
     if (n > _nodes_size) {
-      const double reallocation_factor = 1.3;
-      S new_nodes_size = std::max(n, (S) ((_nodes_size + 1) * reallocation_factor));
-      void *old = _nodes;
-
-      if (_on_disk) {
-        if (!remap_memory_and_truncate(&_nodes, _fd,
-            static_cast<size_t>(_s) * static_cast<size_t>(_nodes_size),
-            static_cast<size_t>(_s) * static_cast<size_t>(new_nodes_size)) &&
-            _verbose)
-            showUpdate("File truncation error\n");
-      } else {
-        _nodes = realloc(_nodes, _s * new_nodes_size);
-        memset((char *) _nodes + (_nodes_size * _s) / sizeof(char), 0, (new_nodes_size - _nodes_size) * _s);
-      }
+      threaded_build_policy.lock_nodes();
+      _reallocate_nodes(n);
+      threaded_build_policy.unlock_nodes();
+    }
+  }
 
-      _nodes_size = new_nodes_size;
-      if (_verbose) showUpdate("Reallocating to %d nodes: old_address=%p, new_address=%p\n", new_nodes_size, old, _nodes);
+  void _allocate_size(S n) {
+    if (n > _nodes_size) {
+      _reallocate_nodes(n);
     }
   }
 
@@ -1179,7 +1225,7 @@ protected:
     return std::max(f, 1-f);
   }
 
-  S _make_tree(const vector<S>& indices, bool is_root) {
+  S _make_tree(const vector<S>& indices, bool is_root, Random& _random, ThreadedBuildPolicy& threaded_build_policy) {
     // The basic rule is that if we have <= _K items, then it's a leaf node, otherwise it's a split node.
     // There's some regrettable complications caused by the problem that root nodes have to be "special":
     // 1. We identify root nodes by the arguable logic that _n_items == n->n_descendants, regardless of how many descendants they actually have
@@ -1189,8 +1235,12 @@ protected:
       return indices[0];
 
     if (indices.size() <= (size_t)_K && (!is_root || (size_t)_n_items <= (size_t)_K || indices.size() == 1)) {
-      _allocate_size(_n_nodes + 1);
+      threaded_build_policy.lock_n_nodes();
+      _allocate_size(_n_nodes + 1, threaded_build_policy);
       S item = _n_nodes++;
+      threaded_build_policy.unlock_n_nodes();
+
+      threaded_build_policy.lock_shared_nodes();
       Node* m = _get(item);
       m->n_descendants = is_root ? _n_items : (S)indices.size();
 
@@ -1200,9 +1250,12 @@ protected:
       // Only copy when necessary to avoid crash in MSVC 9. #293
       if (!indices.empty())
         memcpy(m->children, &indices[0], indices.size() * sizeof(S));
+
+      threaded_build_policy.unlock_shared_nodes();
       return item;
     }
 
+    threaded_build_policy.lock_shared_nodes();
     vector<Node*> children;
     for (size_t i = 0; i < indices.size(); i++) {
       S j = indices[i];
@@ -1233,6 +1286,7 @@ protected:
       if (_split_imbalance(children_indices[0], children_indices[1]) < 0.95)
         break;
     }
+    threaded_build_policy.unlock_shared_nodes();
 
     // If we didn't find a hyperplane, just randomize sides as a last option
     while (_split_imbalance(children_indices[0], children_indices[1]) > 0.99) {
@@ -1259,13 +1313,17 @@ protected:
     m->n_descendants = is_root ? _n_items : (S)indices.size();
     for (int side = 0; side < 2; side++) {
       // run _make_tree for the smallest child first (for cache locality)
-      m->children[side^flip] = _make_tree(children_indices[side^flip], false);
+      m->children[side^flip] = _make_tree(children_indices[side^flip], false, _random, threaded_build_policy);
     }
 
-
-    _allocate_size(_n_nodes + 1);
+    threaded_build_policy.lock_n_nodes();
+    _allocate_size(_n_nodes + 1, threaded_build_policy);
     S item = _n_nodes++;
+    threaded_build_policy.unlock_n_nodes();
+
+    threaded_build_policy.lock_shared_nodes();
     memcpy(_get(item), m, _s);
+    threaded_build_policy.unlock_shared_nodes();
 
     return item;
   }
@@ -1311,7 +1369,7 @@ protected:
     vector<pair<T, S> > nns_dist;
     S last = -1;
     for (size_t i = 0; i < nns.size(); i++) {
-      S j = nns[i];
+      S j = nns[i]; 
       if (j == last)
         continue;
       last = j;
@@ -1330,5 +1388,92 @@ protected:
   }
 };
 
+class AnnoyIndexSingleThreadedBuildPolicy {
+public:
+  template<typename S, typename T, typename D, typename Random>
+  static void build(AnnoyIndex<S, T, D, Random, AnnoyIndexSingleThreadedBuildPolicy>* annoy, int q, int n_threads) {
+    AnnoyIndexSingleThreadedBuildPolicy threaded_build_policy;
+    annoy->thread_build(q, 0, threaded_build_policy);
+  }
+
+  void lock_n_nodes() {}
+  void unlock_n_nodes() {}
+
+  void lock_nodes() {}
+  void unlock_nodes() {}
+
+  void lock_shared_nodes() {}
+  void unlock_shared_nodes() {}
+
+  void lock_roots() {}
+  void unlock_roots() {}
+};
+
+#ifdef ANNOYLIB_MULTITHREADED_BUILD
+class AnnoyIndexMultiThreadedBuildPolicy {
+private:
+  std::shared_timed_mutex nodes_mutex;
+  std::mutex n_nodes_mutex;
+  std::mutex roots_mutex;
+
+public:
+  template<typename S, typename T, typename D, typename Random>
+  static void build(AnnoyIndex<S, T, D, Random, AnnoyIndexMultiThreadedBuildPolicy>* annoy, int q, int n_threads) {
+    AnnoyIndexMultiThreadedBuildPolicy threaded_build_policy;
+    if (n_threads == -1) {
+      // If the hardware_concurrency() value is not well defined or not computable, it returns 0.
+      // We guard against this by using at least 1 thread.
+      n_threads = std::max(1, (int)std::thread::hardware_concurrency());
+    }
+
+    vector<std::thread> threads(n_threads);
+
+    for (int thread_idx = 0; thread_idx < n_threads; thread_idx++) {
+      int trees_per_thread = q == -1 ? -1 : (int)floor((q + thread_idx) / n_threads);
+
+      threads[thread_idx] = std::thread(
+        &AnnoyIndex<S, T, D, Random, AnnoyIndexMultiThreadedBuildPolicy>::thread_build,
+        annoy,
+        trees_per_thread,
+        thread_idx,
+        std::ref(threaded_build_policy)
+      );
+    }
+
+    for (auto& thread : threads) {
+      thread.join();
+    }
+  }
+
+  void lock_n_nodes() {
+    n_nodes_mutex.lock();
+  }
+  void unlock_n_nodes() {
+    n_nodes_mutex.unlock();
+  }
+
+  void lock_nodes() {
+    nodes_mutex.lock();
+  }
+  void unlock_nodes() {
+    nodes_mutex.unlock();
+  }
+
+  void lock_shared_nodes() {
+    nodes_mutex.lock_shared();
+  }
+  void unlock_shared_nodes() {
+    nodes_mutex.unlock_shared();
+  }
+
+  void lock_roots() {
+    roots_mutex.lock();
+  }
+  void unlock_roots() {
+    roots_mutex.unlock();
+  }
+};
+#endif
+
 #endif
 // vim: tabstop=2 shiftwidth=2