shackle

手かせ

高性能 Erlang ネットワーク クライアント フレームワーク

要件

• アーラン 19.0+

特徴

• バックログによるバックプレッシャー (OOM 保護)
• 高速プールの実装 (ランダム、ラウンドロビン)
• 管理されたタイムアウト
• マルチプロトコルのサポート (SSL / TCP / UDP)
• パフォーマンスの最適化
• リクエストのパイプライン化
• スマート再接続メカニズム (指数関数的バックオフ)

フレームワークの目標

• 再利用性
• スピード
• 同時実行性
• 安全性

ハウツー

クライアントの実装

- behavior ( shackle_client ).
- export ([
    init / 0 ,
    setup / 2 ,
    handle_request / 2 ,
    handle_data / 2 ,
    terminate / 1
]).

- record ( state , {
    buffer =       <<>> :: binary (),
    request_counter = 0 :: non_neg_integer ()
}).

- spec init ( Options :: term ()) ->
    { ok , State :: term ()} |
    { error , Reason :: term ()}.

init ( _Options ) ->
    { ok , # state {}}.

- spec setup ( Socket :: inet : socket (), State :: term ()) ->
    { ok , State :: term ()} |
    { error , Reason :: term (), State :: term ()}.

setup ( Socket , State ) ->
    case gen_tcp : send ( Socket , << " INIT " >>) of
        ok ->
            case gen_tcp : recv ( Socket , 0 ) of
                { ok , << " OK " >>} ->
                    { ok , State };
                { error , Reason } ->
                    { error , Reason , State }
            end ;
        { error , Reason } ->
            { error , Reason , State }
    end .

- spec handle_request ( Request :: term (), State :: term ()) ->
    { ok , RequestId :: external_request_id (), Data :: iodata (), State :: term ()}.

handle_request ( noop ,  State ) ->
    Data = arithmetic_protocol : request ( 0 , noop , 0 , 0 ),

    { ok , undefined , Data , State };
handle_request ({ Operation , A , B }, # state {
        request_counter = RequestCounter
    } = State ) ->

    RequestId = request_id ( RequestCounter ),
    Data = request ( RequestId , Operation , A , B ),

    { ok , RequestId , Data , State # state {
        request_counter = RequestCounter + 1
    }}.

- spec handle_data ( Data :: binary (), State :: term ()) ->
    { ok , [{ RequestId :: external_request_id (), Reply :: term ()}], State :: term ()}.

handle_data ( Data , # state {
        buffer = Buffer
    } = State ) ->

    Data2 = << Buffer / binary , Data / binary >>,
    { Replies , Buffer2 } = parse_replies ( Data2 , []),

    { ok , Replies , State # state {
        buffer = Buffer2
    }}.

- spec terminate ( State :: term ()) -> ok .

terminate ( _State ) -> ok .

クライアントプールの開始

 shackle_pool : start ( shackle_pool : name (), client (), client_options (), pool_options ())

クライアントオプション:

名前	タイプ	デフォルト	説明
住所	inet:ip_address() | inet:ホスト名()	「127.0.0.1」	サーバーアドレス (以前の IP)
ポート	inet:ポート番号()	未定義	サーバーポート
プロトコル	シャックル_tcp |シャックル_udp |シャックル_SSL	シャックル_tcp	サーバープロトコル
再接続する	ブール値()	真実	閉じた接続を再接続する
reconnect_time_max	pos_integer() |無限大	120000	最大再接続時間 (ミリ秒)
reconnect_time_min	pos_integer()	1000	最小再接続時間 (ミリ秒)
ソケットオプション	[gen_tcp:connect_option() | gen_udp:オプション()]	[]	ソケットに渡されるオプション

プールオプション:

名前	タイプ	デフォルト	説明
バックログ_サイズ	pos_integer() |無限大	1024	接続ごとの同時リクエストの最大数
max_retries	non_neg_integer()	3	アクティブなサーバーを見つけるための最大試行回数
プールサイズ	pos_integer()	16	接続数
プール戦略	ランダム |ラウンドロビン	ランダム	接続選択戦略

通話/キャストクライアント

 1 > shackle : call ( pool_name , { get , << " test " >>}).
{ ok , << " bar " >>}

2 > { ok , ReqId } = shackle : cast ( pool_name , { get , << " foo " >>}, 500 ).
{ ok , { anchor , anchor_client , # Ref < 0.0 . 0.2407 > }}

3 > shackle : receive_response ( ReqId ).
{ ok , << " bar " >>}

テレメトリー

Shackle は、バックエンドに依存しないテレメトリ ライブラリと統合されます。シャックルが発行できるテレメトリ イベントのリストについては、 shackle_telemetry参照してください。

テスト

make dialyzer
make eunit
make xref

パフォーマンステスト

パフォーマンス テスト ターゲットを実行するには、まずサーバーを起動する必要があります。

 ./bin/server.sh

その後、 benchまたはprofileターゲットを実行できます。

make bench
make profile

クライアント

名前	説明
アンカー	Memcached クライアント
アスパイクノード	エアロスパイククライアント
ブイ	HTTP 1.1 クライアント
フレア	カフカプロデューサー
マリーナ	Cassandra CQL クライアント
統計情報	StatsD クライアント

ライセンス

 The MIT License (MIT)

Copyright (c) 2015-2023 Louis-Philippe Gauthier

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.