Kolus is a library to help you manage your open TCP connections to your various backends. It also helps you balance connections to those backends.
$ make compile
$ erl -pa ebin -env ERL_LIBS deps -s kolus_app
$ make test
Get the current status of the backends. Keep in mind this information
can change fast, and is considered outdated by kolus
as soon as the
caller has it.
[kolus_backend()]|[] = kolus:status([backend()|kolus_backend()]|[])
backend() :: {inet:ip_address(), inet:port_number()}.
kolus_backend() :: #kolus_backend{}.
The #kolus_backend{}
record can be used to match on idle TCP or
unused TCP connections:
#kolus_backend{ ip :: inet:ip_address(),
port :: inet:port_number(),
idle :: pos_integer()|undefined,
unused :: pos_integer()|undefined}.
The idle
and unused
fields will be undefined
if the manager has
not been started or has not been looked up. Do not change values of the
kolus_backend{}
.
Get a socket from the manager, if no socket exists a new one will be made and returned to the caller. If no manager exists for this backend a new manager will be created and a socket will be returned from that manager.
The Ident is used to identify this connection request to the manager, this makes it possible to prevent connection request to different idents to go through the same manager (for example, when a specific Ident is no longer served via a socket).
{socket, kolus_socket()} = kolus:connect(Ident::any(), backend()|
kolus_backend()),
The kolus_socket()
is an opaque type.
Return a socket the caller is done using. The socket will be added back to the manager and made available to other callers.
ok = kolus:return(kolus_socket())
If the manager returns a closed/unusable socket to the caller it can be returned using the following function. The socket will be removed from the managers list.
ok = kolus:finished(kolus_socket())
The kolus_socket()
is an opaque type, you cannot read or write
directly to it.
port() = kolus:get_socket(kolus_socket())
pid() = kolus:get_manager(kolus_socket())
You can specify a search function that's run on the list of backends, this function should return the backend the caller wants to use.
fill_first(Backends) ->
hd(lists:sort(fun(#kolus_backend{idle=A,unused=X},
#kolus_backend{idle=B,unused=Y}) ->
case A > B of
true ->
true;
false ->
case X of
0 ->
false;
_ ->
X =< Y
end
end
end, Backends)).
{socket, Socket} = kolus:select(<<"test">>, Backends, fun ff_filter/1).
For an example check out kolus_demo
Check the LICENSE
file.