Permalink
Browse files

Implement `ask/2` and `done/3`. Also - document.

  • Loading branch information...
1 parent 8077315 commit 67ebe4ead83377c2d3bb8f55e993d449f1af7acf @jlouis committed Sep 24, 2013
Showing with 39 additions and 5 deletions.
  1. +6 −2 README.md
  2. +1 −1 src/safetyvalve.app.src
  3. +32 −2 src/sv.erl
View
@@ -1,6 +1,6 @@
-# Safety Valve
+# Safetyvalve
-The Safety Valve Erlang application provides overload protection for
+The Safetyvalve Erlang application provides overload protection for
Erlang systems. It provides queueing facilities for tasks to be
executed so their concurrency and rate can be limited on a running
system.
@@ -18,6 +18,10 @@ See the document USING.md for a usage example.
# Changes
+### v2.2.0 -> v2.3.0
+
+Add explicit calls to `sv:ask/2` and `sv:done/3`. These calls allows one to run resource acquisition and release in different scopes. While this is slighty dangerous, there are places where one needs exactly this behaviour in systems.
+
### v2.1.0 -> v2.2.0
Allow to pass parameters to queue algorithms. In particular, use this to provide parameters to the CoDel
View
@@ -1,7 +1,7 @@
{application, safetyvalve,
[
{description, "A safety valve for your erlang node"},
- {vsn, "2.2.1"},
+ {vsn, "2.3.0"},
{registered, [safetyvalve_sup]},
{applications, [
kernel,
View
@@ -1,6 +1,6 @@
-module(sv).
--export([timestamp/0]).
+-export([timestamp/0, ask/2, done/3]).
-export([run/2]).
%% Internal API
-export([report/2]).
@@ -32,12 +32,42 @@ run(Name, Fun) ->
{error, Reason}
end.
+%% @doc ask/2 requests the use of a resource in safetyvalve
+%% <p>Ask for the use of a `Queue' at timepoint `T'. Returns either `{go, Ref}' if
+%% you are allowed to use the resource or `{error, Reason}' in case of an error</p>
+%% <p>The timepoint `T' should be generated via a call to `sv:timestamp()'. Also, note
+%% that this call will block until the resource is either given, or the system gives
+%% up on processing the request because it has exceeded some queueing threshold.</p>
+%% <p>When you are done processing, you are obliged to call `sv:done(Queue, Ref, TE)'
+%% where `Ref' is the given reference and `TE' is a time endpoint as given by
+%% a call to `sv:timestamp()'.
+%% @end
+-spec ask(Queue, T) -> {go, Ref} | {error, Reason}
+ when
+ Queue :: atom(),
+ T :: integer(),
+ Ref :: term(), % Opaque
+ Reason :: term().
+ask(QN, T) ->
+ sv_queue:ask(QN, T).
+
+%% @doc done/3 relinquishes a resource yet again to the queue
+%% <p>Call this function when you are done with using a resource. @see ask/2 for the
+%% documentation of how to invoke this function.</p>
+-spec done(Queue, Ref, TE) -> ok
+ when
+ Queue :: atom(),
+ Ref :: term(),
+ TE :: integer().
+done(QN, R, TE) ->
+ sv_queue:done(QN, R, TE).
+
%% @private
report(_T, _Event) ->
hopefully_traced.
%% @doc Construct a timestamp in a canonical way for Safetyvalve.
--spec timestamp() -> term().
+-spec timestamp() -> integer().
timestamp() ->
%% Timestamps *have* to be unique. Calling erlang:now/0 makes sure
%% this happens. But you can use any ordered term if you want, for instance

0 comments on commit 67ebe4e

Please sign in to comment.