Prevent thread safety issue and improve loading operations to be async

.travis.yml

@@ -9,7 +9,7 @@ addons:
 
 language: elixir
 elixir:
-  - 1.4.4
+  - 1.4.5
 
 install:
   - export CC="clang"

Makefile

@@ -28,12 +28,9 @@ all: libpostal
 libpostal:
 	$(MIX) compile
 
-priv/parser.so: src/parser.c
-	$(CC) $(CFLAGS) -shared $(LDFLAGS) -o $@ src/parser.c
-
-priv/expand.so: src/expand.c
-	$(CC) $(CFLAGS) -shared $(LDFLAGS) -o $@ src/expand.c
+priv/expostal.so: src/expostal.c
+	$(CC) $(CFLAGS) -shared $(LDFLAGS) -o $@ src/expostal.c
 
 clean:
 	$(MIX) clean
-	$(RM) priv/*
+	$(RM) priv/*

README.md

@@ -15,7 +15,7 @@ The package can be installed by adding `expostal` to your list of dependencies i
 
 ```elixir
 def deps do
-  [{:expostal, "~> 0.1.0"}]
+  [{:expostal, "~> 0.2.0"}]
 end
 ```
 
@@ -30,7 +30,7 @@ Depends on [system-wide installation of libpostal](https://github.com/openvenues
 Parsing an address: 
 
 ```
-iex> Expostal.Parser.parse_address("615 Rene Levesque Ouest, Montreal, QC, Canada")
+iex> Expostal.parse_address("615 Rene Levesque Ouest, Montreal, QC, Canada")
 
 %{city: "montreal", country: "canada", house_number: "615",
   road: "rene levesque ouest", state: "qc"}
@@ -40,7 +40,7 @@ iex> Expostal.Parser.parse_address("615 Rene Levesque Ouest, Montreal, QC, Canad
 Expanding an address: 
 
 ```
-iex> Expostal.Expand.expand_address("781 Franklin Ave Crown Hts Brooklyn NY")
+iex> Expostal.expand_address("781 Franklin Ave Crown Hts Brooklyn NY")
 
 ["781 franklin avenue crown heights brooklyn new york",
   "781 franklin avenue crown heights brooklyn ny"]

lib/expostal.ex

@@ -0,0 +1,76 @@
+defmodule Expostal do
+  @moduledoc """
+  Address parsing and expansion module for Openvenue's Libpostal, which does parses addresses.
+  """
+
+  @compile { :autoload, false }
+  @on_load { :init, 0 }
+
+  app = Mix.Project.config[:app]
+
+  defp init do
+    path = :filename.join(:code.priv_dir(unquote(app)), 'expostal')
+    :ok = :erlang.load_nif(path, 0)
+  end
+
+  @doc """
+  Loads the large dataset from disk for libpostal and prepares it for future calls.
+
+  If you do not run this explicitly, then it will be run by `parse_address/1` or `expand_address/1`
+  on their first run. This is a very slow process (it can take 10s of seconds), so if you value
+  the responsiveness of your application, you can spawn a secondary thread to run this bootstrap
+  in the background on your application startup:
+
+  ```
+  spawn(fn -> Expostal.bootstrap end)
+  ```
+
+  This will prevent you IEx shell from hanging during startup and will make the library much more
+  likely to be ready for immediate usage for your first call.
+
+  """
+  def bootstrap do
+    case :erlang.phash2(1, 1) do
+      0 -> raise "Nif not loaded"
+      1 -> :ok
+      2 -> :error
+    end
+  end
+
+  @doc """
+  Parse given address into a map of address components
+
+  ## Examples
+
+      iex> Expostal.Parser.parse_address("615 Rene Levesque Ouest, Montreal, QC, Canada")
+      %{city: "montreal", country: "canada", house_number: "615",
+        road: "rene levesque ouest", state: "qc"}
+
+  """
+  @spec parse_address(address :: String.t) :: map
+  def parse_address(address)
+  def parse_address(_) do
+    case :erlang.phash2(1, 1) do
+      0 -> raise "Nif not loaded"
+      1 -> %{}
+    end
+  end
+
+  @doc """
+  Expand given address into a list of expansions
+
+  ## Examples
+    iex> Expostal.Expand.expand_address("781 Franklin Ave Crown Hts Brooklyn NY")
+    ["781 franklin avenue crown heights brooklyn new york",
+     "781 franklin avenue crown heights brooklyn ny"]
+
+  """
+  @spec expand_address(address :: String.t) :: [String.t]
+  def expand_address(address) do
+    case :erlang.phash2(1, 1) do
+      0 -> raise "Nif not loaded"
+      1 -> [address]
+    end
+  end
+
+end

mix.exs

@@ -6,9 +6,7 @@ defmodule Mix.Tasks.Compile.Libpostal do
       exit(1)
     else
       File.mkdir_p("priv")
-      {result, _error_code} = System.cmd("make", ["priv/parser.so"], stderr_to_stdout: true)
-      IO.binwrite result
-      {result, _error_code} = System.cmd("make", ["priv/expand.so"], stderr_to_stdout: true)
+      {result, _error_code} = System.cmd("make", ["priv/expostal.so"], stderr_to_stdout: true)
       IO.binwrite result
     end
     :ok
@@ -20,7 +18,7 @@ defmodule Expostal.Mixfile do
 
   def project do
     [app: :expostal,
-     version: "0.1.5",
+     version: "0.2.0",
      elixir: "~> 1.4",
      build_embedded: Mix.env == :prod,
      start_permanent: Mix.env == :prod,