Skip to content
Browse files

Initial documentation

  • Loading branch information...
1 parent 8e645a2 commit ef44ade0481ecb16e4f69dfe1a5cd0e0ce653afe @evax evax committed Mar 4, 2011
Showing with 250 additions and 30 deletions.
  1. +2 −0 Makefile
  2. +43 −0 doc/overview.edoc
  3. +86 −12 include/ezmq.hrl
  4. +116 −17 src/ezmq.erl
  5. +1 −0 src/ezmq_app.erl
  6. +1 −0 src/ezmq_nif.erl
  7. +1 −1 src/ezmq_sup.erl
View
2 Makefile
@@ -26,3 +26,5 @@ perf: compile
test: compile
@./rebar eunit
+docs:
+ @./rebar doc
View
43 doc/overview.edoc
@@ -0,0 +1,43 @@
+@title NIF based Erlang bindings for the ZeroMQ messaging library.
+@copyright 2011 Yurii Rashkovskii and Evax Sofware
+@author Yurii Rashkovskii <yrashk@gmail.com> [http://rashkovskii.com]
+@author Evax Software <contact@evax.fr> [http://www.evax.fr]
+@reference The <a href="http://www.zeromq.org">ZeroMQ</a> messaging library.
+@doc
+
+<ol>
+<li>{@section Overview}</li>
+<li>{@section Downloading}</li>
+<li>{@section Building}</li>
+</ol>
+
+== Overview ==
+
+The ezmq application provides high-performance NIF based Erlang bindings
+for the ZeroMQ messaging library.
+
+== Downloading ==
+
+The ezmq source code can be found on [http://github.com/yrashk/ezmq GitHub]
+
+```
+ $ git clone http://github.com/yrashk/ezmq.git
+'''
+
+== Building ==
+
+Build the code
+```
+ $ make
+'''
+
+Build the docs
+```
+ $ make docs
+'''
+
+Run the test suite
+```
+ $ make test
+'''
+
View
98 include/ezmq.hrl
@@ -37,32 +37,106 @@
-define('ZMQ_SNDMORE', 2).
%% Types
--type ezmq_socket_type() :: pair | pub | sub | req | rep | xreq | xrep | pull | push | xpub | xsub.
+
+%% @type ezmq_socket_type() = pair | pub | sub | req | rep | xreq | xrep |
+%% pull | push | xpub | xsub.
+%% Possible types for an ezmq socket.<br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_socket">zmq_socket</a></i>
+-type ezmq_socket_type() :: pair | pub | sub | req | rep | xreq | xrep |
+ pull | push | xpub | xsub.
+
+%% @type ezmq_endpoint() = string().
+%% The endpoint argument is a string consisting of two parts:
+%% <b>transport://address</b><br />
+%% The following transports are defined:
+%% <b>inproc</b>, <b>ipc</b>, <b>tcp</b>, <b>pgm</b>, <b>epgm</b>.<br />
+%% The meaning of address is transport specific.<br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_bind">zmq_bind</a> or
+%% <a href="http://api.zeromq.org/master:zmq_connect">zmq_connect</a></i>
-type ezmq_endpoint() :: string().
--type errno() :: eperm | enoent | srch | eintr | eio | enxio | ebad | echild | edeadlk | enomem | eacces | efault |
- enotblk | ebusy | eexist | exdev | enodev | enotdir | eisdir | einval | enfile | emfile | enotty |
- etxtbsy | efbig | enospc | espipe | erofs | emlink | epipe | eagain | einprogress | ealready |
- enotsock | edestaddrreq | emsgsize | eprototype | enoprotoopt | eprotonosupport | esocktnosupport |
- enotsup | epfnosupport | eafnosupport | eaddrinuse | eaddrnotavail | enetdown | enetunreach |
- enetreset | econnaborted | econnreset | enobufs | eisconn | enotconn | eshutdown | etoomanyrefs |
+%% @type errno() = eperm | enoent | srch | eintr | eio | enxio | ebad |
+%% echild | edeadlk | enomem | eacces | efault | enotblk | ebusy | eexist |
+%% exdev | enodev | enotdir | eisdir | einval | enfile | emfile | enotty |
+%% etxtbsy | efbig | enospc | espipe | erofs | emlink | epipe | eagain |
+%% einprogress | ealready | enotsock | edestaddrreq | emsgsize |
+%% eprototype | enoprotoopt | eprotonosupport | esocktnosupport |
+%% enotsup | epfnosupport | eafnosupport | eaddrinuse | eaddrnotavail |
+%% enetdown | enetunreach | enetreset | econnaborted | econnreset |
+%% enobufs | eisconn | enotconn | eshutdown | etoomanyrefs | etimedout |
+%% econnrefused | eloop | enametoolong.
+%% Standard error atoms.
+-type errno() :: eperm | enoent | srch | eintr | eio | enxio | ebad |
+ echild | edeadlk | enomem | eacces | efault | enotblk |
+ ebusy | eexist | exdev | enodev | enotdir | eisdir |
+ einval | enfile | emfile | enotty | etxtbsy | efbig |
+ enospc | espipe | erofs | emlink | epipe | eagain |
+ einprogress | ealready | enotsock | edestaddrreq |
+ emsgsize | eprototype | enoprotoopt | eprotonosupport |
+ esocktnosupport | enotsup | epfnosupport | eafnosupport |
+ eaddrinuse | eaddrnotavail | enetdown | enetunreach |
+ enetreset | econnaborted | econnreset | enobufs | eisconn |
+ enotconn | eshutdown | etoomanyrefs |
etimedout | econnrefused | eloop | enametoolong.
--type ezmq_error_type() :: enotsup | eprotonosupport | enobufs | enetdown | eaddrinuse | eaddnotavail | econnrefused |
- einprogress | efsm | enocompatproto | eterm | emthread | errno() | {unknown, integer()}.
+%% @type ezmq_error_type() = enotsup | eprotonosupport | enobufs |
+%% enetdown | eaddrinuse | eaddnotavail | econnrefused | einprogress |
+%% efsm | enocompatproto | eterm | emthread | errno() |
+%% {unknown, integer()}.
+%% Possible error types.
+-type ezmq_error_type() :: enotsup | eprotonosupport | enobufs | enetdown |
+ eaddrinuse | eaddnotavail | econnrefused |
+ einprogress | efsm | enocompatproto | eterm |
+ emthread | errno() | {unknown, integer()}.
+%% @type ezmq_error() = {error, ezmq_error_type()} | {error, timeout(), reference()}.
+%% Error tuples returned by most API functions.
-type ezmq_error() :: {error, ezmq_error_type()} | {error, timeout(), reference()}.
+%% @type ezmq_data() = iolist().
+%% Data to be sent with {@link ezmq:send/3. send/3} or received with
+%% {@link ezmq:recv/2. recv/2}
-type ezmq_data() :: iolist().
+%% @type ezmq_context() = binary().
+%% An opaque handle to an ezmq context.
-opaque ezmq_context() :: binary().
+
+%% @type ezmq_socket() = binary().
+%% An opaque handle to an ezmq socket.
-opaque ezmq_socket() :: binary().
--type ezmq_send_recv_flag() :: noblock | sndmore | {timeout, timeout()}.
+%% @type ezmq_send_recv_flag() = noblock | sndmore | recvmore | {timeout, timeout()}.
+%% The individual flags to use with {@link ezmq:send/3. send/3}
+%% and {@link ezmq:recv/2. recv/2}.<br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_send">zmq_send</a> or
+%% <a href="http://api.zeromq.org/master:zmq_recv">zmq_recv</a></i>
+-type ezmq_send_recv_flag() :: noblock | sndmore | recvmore | {timeout, timeout()}.
+
+%% @type ezmq_send_recv_flags() = list(ezmq_send_recv_flag).
+%% A list of flags to use with {@link ezqm:send/3. send/3} and
+%% {@link ezmq:recv/2. recv/2}
-type ezmq_send_recv_flags() :: list(ezmq_send_recv_flag).
--type ezmq_sockopt() :: hwm | swap | affinity | identity | subscribe | unsubscribe | rate | recovery_ivl | mcast_loop |
- sndbuf | rcvbuf | rcvmore | fd | events | linger | reconnect_ivl | backlog | recovery_ivl_msec |
+%% @type ezmq_sockopt() = hwm | swap | affinity | identity | subscribe |
+%% unsubscribe | rate | recovery_ivl | mcast_loop | sndbuf | rcvbuf |
+%% rcvmore | fd | events | linger | reconnect_ivl | backlog |
+%% recovery_ivl_msec | reconnect_ivl_max.
+%% Available options for {@link ezmq:setsockopt/3. setsockopt/3}
+%% and {@link ezmq:getsockopt/2. getsockopt/2}.<br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_setsockopt">zmq_setsockopt</a>
+%% and <a href="http://api.zeromq.org/master:zmq_getsockopt">zmq_getsockopt</a></i>
+-type ezmq_sockopt() :: hwm | swap | affinity | identity | subscribe |
+ unsubscribe | rate | recovery_ivl | mcast_loop |
+ sndbuf | rcvbuf | rcvmore | fd | events | linger |
+ reconnect_ivl | backlog | recovery_ivl_msec |
reconnect_ivl_max.
+%% @type ezmq_sockopt_value() = integer() | iolist().
+%% Possible option values for {@link ezmq:setsockopt/3. setsockopt/3}.
-type ezmq_sockopt_value() :: integer() | iolist().
+
View
133 src/ezmq.erl
@@ -1,58 +1,126 @@
-module(ezmq).
+%% @headerfile "ezmq.hrl"
-include_lib("ezmq.hrl").
--export([context/0, context/1, socket/2, bind/2, connect/2, send/2, send/3, brecv/1, brecv/2, recv/1, recv/2, setsockopt/3, getsockopt/2, close/1, term/1, term/2]).
+-export([context/0, context/1, socket/2, bind/2, connect/2, send/2, send/3,
+ brecv/1, brecv/2, recv/1, recv/2, setsockopt/3, getsockopt/2,
+ close/1, term/1, term/2]).
-export_type([ezmq_socket/0, ezmq_context/0]).
--spec context() -> ezmq_context().
-
+%% @equiv context(1)
+%% @spec context() -> {ok, ezmq_context()} | ezmq_error()
+-spec context() -> {ok, ezmq_context()} | ezmq_error().
context() ->
context(1).
--spec context(Threads :: pos_integer()) -> ezmq_context().
-
+%% @doc Create a new ezmq context with the specified number of io threads.
+%% <br />
+%% If the context can be created an 'ok' tuple containing an
+%% {@type ezmq_context()} handle to the created context is returned;
+%% if not, it returns an 'error' tuple with an {@type ezmq_type_error()}
+%% describing the error.
+%% <br />
+%% The context must be later cleaned up calling {@link ezmq:term/1. term/1}
+%% <br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq-init">zmq_init</a></i>
+%% @end
+%% @spec context(pos_integer()) -> {ok, ezmq_context()} | ezmq_error()
+-spec context(Threads :: pos_integer()) -> {ok, ezmq_context()} | ezmq_error().
+
context(Threads) when is_integer(Threads) ->
ezmq_nif:context(Threads).
--spec socket(Context :: ezmq_context(), Type :: ezmq_socket_type()) -> ezmq_socket().
-
+
+%% @doc Create a socket.
+%% <br />
+%% This functions creates a socket of the given
+%% {@link ezmq_socket_type(). type} and associates it with the given
+%% {@link ezmq_context(). context}.
+%% <br />
+%% If the socket can be created an 'ok' tuple containing a
+%% {@type ezmq_socket()} handle to the created socket is returned;
+%% if not, it returns an {@type ezmq_error()} describing the error.<br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_socket">zmq_socket</a>.</i>
+%% @end
+%% @spec socket(ezmq_context(), ezmq_socket_type()) -> {ok, ezmq_socket()} | ezmq_error()
+-spec socket(Context :: ezmq_context(), Type :: ezmq_socket_type()) -> {ok, ezmq_socket()} | ezmq_error().
+
socket(Context, Type) ->
ezmq_nif:socket(Context, socket_type(Type)).
+%% @doc Accept connections on a socket.
+%% <br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_bind">zmq_bind</a>.</i>
+%% @end
+%% @spec bind(ezmq_socket(), ezmq_endpoint()) -> ok | ezmq_error()
-spec bind(Socket :: ezmq_socket(), Endpoint :: ezmq_endpoint()) -> ok | ezmq_error().
-
+
bind(Socket, Endpoint) ->
ezmq_result(ezmq_nif:bind(Socket, Endpoint)).
+%% @doc Connect a socket.
+%% <br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_connect">zmq_connect</a>.</i>
+%% @end
+%% @spec connect(ezmq_socket(), ezmq_endpoint()) -> ok | ezmq_error()
-spec connect(Socket :: ezmq_socket(), Endpoint :: ezmq_endpoint()) -> ok | ezmq_error().
-
+
connect(Socket, Endpoint) ->
ezmq_result(ezmq_nif:connect(Socket, Endpoint)).
+%% @equiv send(Socket, Msg, 0)
+%% @spec send(ezmq_socket(), ezmq_data()) -> ok | ezmq_error()
-spec send(Socket :: ezmq_socket(), Data :: ezmq_data()) -> ok | ezmq_error().
-
+
send(Socket, Binary) ->
ezmq_result(send(Socket, Binary, [])).
+%% @doc Send a message on a socket.
+%% <br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_send">zmq_send</a>.</i>
+%% @end
+%% @spec send(ezma_socket(), ezmq_data(), ezmq_send_recv_flags()) -> ok | ezmq_error()
-spec send(Socket :: ezmq_socket(), Data :: ezmq_data(), Flags :: ezmq_send_recv_flags()) -> ok | ezmq_error().
send(Socket, Binary, Flags) when is_list(Flags) ->
ezmq_result(ezmq_nif:send(Socket, Binary, sendrecv_flags(Flags))).
+%% @equiv brecv(Socket, 0)
+%% @deprecated
+%% @spec brecv(ezmq_socket()) -> {ok, ezmq_data()} | ezmq_error()
-spec brecv(Socket :: ezmq_socket()) -> {ok, ezmq_data()} | ezmq_error().
-
+
brecv(Socket) ->
ezmq_result(brecv(Socket, [])).
+%% @doc Receive a message from a socket in a blocking way.
+%% This function can block the current VM thread. <b>DO NOT USE</b>.
+%% @end
+%% @deprecated
+%% @spec brecv(ezmq_socket(), ezmq_send_recv_flags()) -> {ok, ezmq_data()} | ezmq_error()
-spec brecv(Socket :: ezmq_socket(), Flags :: ezmq_send_recv_flags()) -> {ok, ezmq_data()} | ezmq_error().
brecv(Socket, Flags) when is_list(Flags) ->
ezmq_result( ezmq_nif:brecv(Socket, sendrecv_flags(Flags))).
+
+%% @equiv recv(Socket, 0)
+%% @spec recv(ezmq_socket()) -> {ok, ezmq_data()} | ezmq_error()
-spec recv(Socket :: ezmq_socket()) -> {ok, ezmq_data()} | ezmq_error().
recv(Socket) ->
ezmq_result(recv(Socket, [])).
+%% @doc Receive a message from a socket.
+%% <br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_recv">zmq_recv</a>.</i>
+%% @end
+%% @spec recv(ezmq_socket(), ezmq_send_recv_flags()) -> {ok, ezmq_data()} | ezmq_error()
-spec recv(Socket :: ezmq_socket(), Flags :: ezmq_send_recv_flags()) -> {ok, ezmq_data()} | ezmq_error().
recv(Socket, Flags) when is_list(Flags) ->
@@ -69,26 +137,57 @@ recv(Socket, Flags) when is_list(Flags) ->
ezmq_result(Result)
end.
+%% @doc Set an {@link ezmq_sockopt(). option} associated with a socket.
+%% <br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_setsockopt">zmq_setsockopt</a>.</i>
+%% @end
+%% @spec setsockopt(ezmq_socket(), ezmq_sockopt(), ezmq_sockopt_value()) -> ok | ezmq_error()
-spec setsockopt(Socket :: ezmq_socket(), Name :: ezmq_sockopt(), ezmq_sockopt_value()) -> ok | ezmq_error().
-
+
setsockopt(Socket, Name, Value) ->
ezmq_result(ezmq_nif:setsockopt(Socket, option_name(Name), Value)).
+%% @doc Get an {@link ezmq_sockopt(). option} associated with a socket.
+%% <br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_getsockopt">zmq_getsockopt</a>.</i>
+%% @end
+%% @spec getsockopt(ezmq_socket(), ezmq_sockopt()) -> {ok, ezmq_sockopt_value()} | ezmq_error()
-spec getsockopt(Socket :: ezmq_socket(), Name :: ezmq_sockopt()) -> {ok, ezmq_sockopt_value()} | ezmq_error().
-
+
getsockopt(Socket, Name) ->
ezmq_result(ezmq_nif:getsockopt(Socket, option_name(Name))).
+
+%% @doc Close the given socket.
+%% <br />
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_close">zmq_close</a>.</i>
+%% @end
+%% @spec close(ezmq_socket()) -> ok | ezmq_error()
-spec close(Socket :: ezmq_socket()) -> ok | ezmq_error().
-
+
close(Socket) ->
ezmq_result(ezmq_nif:close(Socket)).
+%% @equiv term(Context, infinity)
+%% @spec term(ezmq_context()) -> ok | ezmq_error()
-spec term(Context :: ezmq_context()) -> ok | ezmq_error().
term(Context) ->
term(Context, infinity).
-
+
+
+%% @doc Terminate the given context waiting up to Timeout ms.
+%% <br />
+%% This function should be called after all sockets associated with
+%% the given context have been closed.<br />
+%% If not it will block the given Timeout amount of time.
+%% <i>For more information see
+%% <a href="http://api.zeromq.org/master:zmq_term">zmq_term</a>.</i>
+%% @end
+%% @spec term(ezmq_context(), timeout()) -> ok | ezmq_error()
-spec term(Context :: ezmq_context(), Timeout :: timeout()) -> ok | ezmq_error().
term(Context, Timeout) ->
@@ -108,7 +207,7 @@ term(Context, Timeout) ->
%% Private
-spec socket_type(Type :: ezmq_socket_type()) -> integer().
-
+
socket_type(pair) ->
?'ZMQ_PAIR';
socket_type(pub) ->
@@ -144,7 +243,7 @@ sendrecv_flags([sndmore|Rest]) ->
?'ZMQ_SNDMORE' bor sendrecv_flags(Rest).
-spec option_name(Name :: ezmq_sockopt()) -> integer().
-
+
option_name(hwm) ->
?'ZMQ_HWM';
option_name(swap) ->
View
1 src/ezmq_app.erl
@@ -1,3 +1,4 @@
+%% @hidden
-module(ezmq_app).
-behaviour(application).
View
1 src/ezmq_nif.erl
@@ -1,3 +1,4 @@
+%% @hidden
-module(ezmq_nif).
-export([context/1, socket/2, bind/2, connect/2, send/3, brecv/2, recv/2, setsockopt/3, getsockopt/2, close/1, term/1]).
View
2 src/ezmq_sup.erl
@@ -1,4 +1,4 @@
-
+%% @hidden
-module(ezmq_sup).
-behaviour(supervisor).

0 comments on commit ef44ade

Please sign in to comment.
Something went wrong with that request. Please try again.