%
%  |   /¯\ /¯_ /¯_ |_¯ |¯\     | |     /¯  /¯\ |\/| |\/| /¯\ |\ |              
%  |__ \_/ \_/ \_/ |__ |¯\ ___ |¯| ___ \_, \_/ |  | |  | \_/ | \|  .   H  R  L 
%
%%%-----------------------------------------------------------------
%%% Overload protection configuration

%%! *** NOTE *** 
%%! It's important that:
%%! SYNC_MODE_QLEN =< DROP_MODE_QLEN =< FLUSH_QLEN
%%! and that DROP_MODE_QLEN >= 2.
%%! Otherwise the handler could end up in drop mode with no new
%%! log requests to process. This would cause all future requests
%%! to be dropped (no switch to async mode would ever take place).


%% This specifies the message_queue_len value where the log
%% requests switch from asynchronous casts to synchronous calls.
-define( SYNC_MODE_QLEN,   10 ).


%% Above this message_queue_len, log requests will be dropped,
%% i.e. no log requests get sent to the handler process.
-define( DROP_MODE_QLEN,  200 ).


%% Above this message_queue_len, the handler process will flush
%% its mailbox and only leave this number of messages in it.
-define(     FLUSH_QLEN, 1000 ).


%% Never flush more than this number of messages in one go,
%% or the handler will be unresponsive for seconds (keep this
%% number as large as possible or the mailbox could grow large).
-define(    FLUSH_MAX_N, 5000 ).



%% BURST_LIMIT_MAX_COUNT is the max number of log requests allowed
%% to be written within a BURST_LIMIT_WINDOW_TIME time frame.
-define( BURST_LIMIT_ENABLE     , true).
-define( BURST_LIMIT_MAX_COUNT  ,  500).
-define( BURST_LIMIT_WINDOW_TIME, 1000).



%% This enables/disables the feature to automatically get the
%% handler terminated if it gets too loaded (and can't keep up).
-define(  OVERLOAD_KILL_ENABLE  ,   false).
%% If the message_queue_len goes above this size even after
%% flushing has been performed, the handler is terminated.
-define(  OVERLOAD_KILL_QLEN    ,   20000).
%% If the memory usage exceeds this level
-define(  OVERLOAD_KILL_MEM_SIZE, 3000000).

%% This is the default time that the handler will wait before
%% restarting and accepting new requests. The value 'infinity'
%% disables restarts.
-define(OVERLOAD_KILL_RESTART_AFTER, 5000).
%%-define(OVERLOAD_KILL_RESTART_AFTER, infinity).



%% The handler sends asynchronous write requests to the process
%% controlling the i/o device, but every once in this interval
%% will the write request be synchronous, so that the i/o device
%% process doesn't get overloaded. This gives the handler time
%% to keep up with its mailbox in overload situations, even if
%% the i/o is slow.
-define(CONTROLLER_SYNC_INTERVAL, 20).
%% The handler will not perform a file sync operation if the
%% mailbox size is greater than this number. This is to ensure
%% the handler process doesn't get overloaded while waiting for
%% an expensive file sync operation to finish.
-define(FILESYNC_OK_QLEN, 2). 
%% Do a file/disk_log sync operation every integer() millisec
%% (if necessary) or set to 'no_repeat' to only do file sync when
%% the handler is idle. Note that file sync is not guaranteed to
%% happen automatically if this operation is disabled.
-define(FILESYNC_REPEAT_INTERVAL, 5000).
%%-define(FILESYNC_REPEAT_INTERVAL, no_repeat).



%% This is the time after last message received that we think/hope
%% that the handler has an empty mailbox (no new log request has
%% come in).
-define(IDLE_DETECT_TIME_MSEC,    100).
-define(IDLE_DETECT_TIME_USEC, 100000).


%% Default disk log option values
-define(DISK_LOG_TYPE        ,    wrap).
-define(DISK_LOG_MAX_NO_FILES,      10).
-define(DISK_LOG_MAX_NO_BYTES, 1048576).

%%%-----------------------------------------------------------------
%%% Utility macros

-define(   name_to_reg_name( MODULE ,      Name)
                                    ,
  list_to_atom(lists:concat([MODULE , "_", Name]))).



%%%-----------------------------------------------------------------
%%% Overload protection macros


%  ¯|¯  | |\/| |_¯  (` ¯|¯  /\  |\/| |¯\ 
%   |   | |  | |__ \_)  |  /¯¯\ |  | |¯¯ 
%
-define( timestamp() , erlang:monotonic_time(microsecond) ).


%  /¯_ |_¯ ¯|¯     |\/| /¯\ |¯\ |_¯ 
%  \_/ |__  |  ___ |  | \_/ |_/ |__ 
%
-define(   get_mode(Tid)
        ,
          case 
          ets:lookup(Tid, mode) 
                      of
           [{mode,M}] -> M;
                  _   -> async
                     end
       ).


%   (` |_¯ ¯|¯     |\/| /¯\ |¯\ |_¯ 
%  \_) |__  |  ___ |  | \_/ |_/ |__ 
%
-define(    set_mode(       Tid    ,   M )
        ,
           begin ets:insert(Tid, {mode,M}) 
               , M 
             end
          )
         .


%  /¯  | |  /\  |\ | /¯_ |_¯     |\/| /¯\ |¯\ |_¯ 
%  \_, |¯| /¯¯\ | \| \_/ |__ ___ |  | \_/ |_/ |__ 
%
-define( change_mode(Tid, M0, M1) 
        ,
                    if 
           M0 == M1 -> M0
              ;true -> ets:insert(Tid, {mode,M1}),
                       M1
        end).


%  |\/|  | |\ | 
%  |  |  | | \| 
%
-define( min(X1, X2)
        ,
                         if 
         X2 == undefined -> X1 ;
                 X2 < X1 -> X2 ;
                    true -> X1
                        end     ).


%  |\/|  /\  \/ 
%  |  | /¯¯\ /\ 
%
-define( max(X1, X2)
        ,
                            if 
            X2 == undefined -> X1 ;
                    X2 > X1 -> X2 ;
                       true -> X1
                           end    ).


%  |¯\  | |¯¯ |¯¯    ¯|¯  | |\/| |_¯ 
%  |_/  | |¯  |¯      |   | |  | |__
%
-define( diff_time( OS_T1 , OS_T0 ) ,  OS_T1 - OS_T0 ).




%%%-----------------------------------------------------------------
%%% The test hook macros make it possible to observe and manipulate
%%% internal handler functionality. When enabled, these macros will
%%% slow down execution and therefore should not be include in code
%%% to be officially released.

%%-define(TEST_HOOKS, true).
-ifdef(TEST_HOOKS).

  -define(TEST_HOOKS_TAB, logger_h_test_hooks).



  -define( init_test_hooks(),
          _ = case 
              ets:whereis(?TEST_HOOKS_TAB) 
                            of
                  undefined -> ets:new(?TEST_HOOKS_TAB, [named_table,public]);
                  _         -> ok
                           end
                          ,
          ets:insert(?TEST_HOOKS_TAB, {internal_log  ,{logger,internal_log}}) ,
          ets:insert(?TEST_HOOKS_TAB, {file_write    ,      ok             }) ,
          ets:insert(?TEST_HOOKS_TAB, {file_datasync ,      ok             }) ,
          ets:insert(?TEST_HOOKS_TAB, {disk_log_write,      ok             }) ,
          ets:insert(?TEST_HOOKS_TAB, {disk_log_sync ,      ok             })
         )
        .


  -define(set_internal_log(               MOD_FUNC )
          ,
            ets:insert( ?TEST_HOOKS_TAB
                       , { internal_log , MOD_FUNC }
                        )
            ).

            
  -define(set_result(                              OPERATION,RESULT ),
                      ets:insert(?TEST_HOOKS_TAB, {OPERATION,RESULT})).


  -define( set_defaults(),
                          ets:insert(?TEST_HOOKS_TAB, {internal_log  ,{logger,internal_log}}),
                          ets:insert(?TEST_HOOKS_TAB, {file_write    ,         ok          }),
                          ets:insert(?TEST_HOOKS_TAB, {file_datasync ,         ok          }),
                          ets:insert(?TEST_HOOKS_TAB, {disk_log_write,         ok          }),
                          ets:insert(?TEST_HOOKS_TAB, {disk_log_sync ,         ok          })
                        ).

  -define( internal_log(                                  TYPE, TERM )
          ,
           try 
            ets:lookup(?TEST_HOOKS_TAB, internal_log) 
                                  of
               [{_,{LMOD,LFUNC}}] -> apply(LMOD, LFUNC, [ TYPE, TERM]);
                              ; _ -> logger:internal_log( TYPE, TERM )
            catch 
              _:_ -> logger:internal_log(TYPE, TERM) end).




  -define( file_write(                  DEVICE, DATA),
          try 
          ets:lookup(?TEST_HOOKS_TAB, file_write) 
                          of
              [{_,ok}]    -> file:write(DEVICE, DATA);
              [{_,ERROR}] -> ERROR
          catch
             _:_ -> file:write(         DEVICE, DATA) end).



  -define( file_datasync(                  DEVICE),
          try 
          ets:lookup(?TEST_HOOKS_TAB, file_datasync) 
                          of
              [{_,ok}]    -> file:datasync(DEVICE);
              [{_,ERROR}] -> ERROR
          catch
             _:_ -> file:datasync(         DEVICE) end).



  -define( disk_log_write(                  LOG, MODE, DATA),
          try 
          ets:lookup(?TEST_HOOKS_TAB, disk_log_write) 
                          of
              [{_,ok}]    -> disk_log_write(LOG, MODE, DATA);
              [{_,ERROR}] -> ERROR
          catch
             _:_ -> disk_log_write(         LOG, MODE, DATA) end).



  -define( disk_log_sync(                  LOG),
          try 
          ets:lookup(?TEST_HOOKS_TAB, disk_log_sync) 
                          of
              [{_,ok}]    -> disk_log:sync(LOG);
              [{_,ERROR}] -> ERROR
          catch
             _:_ -> disk_log:sync(         LOG) end).





  -define(DEFAULT_CALL_TIMEOUT, 5000).


-else.                                          % DEFAULTS!
  -define(TEST_HOOKS_TAB                 , undefined                      ).
  -define(init_test_hooks()              , ok                             ).
  -define(set_internal_log(_MOD_FUNC)    , ok                             ).
  -define(set_result(_OPERATION, _RESULT), ok                             ).
  -define(set_defaults()                 , ok                             ).
  -define(internal_log(TYPE, TERM)       , logger:internal_log(TYPE, TERM)).
  -define(file_write(DEVICE, DATA)       , file:write(DEVICE, DATA)       ).
  -define(file_datasync(DEVICE)          , file:datasync(DEVICE)          ).
  -define(disk_log_write(LOG, MODE, DATA), disk_log_write(LOG, MODE, DATA)).
  -define(disk_log_sync(LOG)             , disk_log:sync(LOG)             ).
  -define(DEFAULT_CALL_TIMEOUT           , 10000                          ).

-endif.





%%%-----------------------------------------------------------------
%%% These macros enable statistics counters in the state of the
%%% handler which is useful for analysing the overload protection
%%% behaviour. These counters should not be included in code to be
%%% officially released (as some counters will grow very large
%%% over time).

%%-define(SAVE_STATS, true).

-ifdef(SAVE_STATS).

  -define(merge_with_stats(STATE)
          ,
            STATE#{     flushes => 0
                  ,     flushed => 0
                  ,       drops => 0
                  , burst_drops => 0
                  ,       casts => 0
                  ,       calls => 0
                  ,    max_qlen => 0
                  ,    max_time => 0
                }).


  -define(  update_max_qlen(         QLEN   ,  STATE ),
           begin 
                 #{max_qlen :=       QLEN0 } = STATE,
           STATE#{ max_qlen  => ?max(QLEN0,QLEN) } 
           end).



  -define(   update_calls_or_casts( CALL_OR_CAST, INC, STATE ),
          case 
          CALL_OR_CAST 
                    of

               cast ->
                           #{casts := CASTS0} = STATE,
                      STATE#{casts => CASTS0 + INC}

              ;call ->
                           #{calls := CALLS0} = STATE,
                      STATE#{calls => CALLS0 + INC}

                   end
            ).


  -define(      update_max_time(         TIME   , STATE),
          begin      #{max_time :=       TIME0} = STATE,
                STATE#{max_time  => ?max(TIME0,TIME) } 
          end
         ).


  -define(update_other(OTHER  , VAR   , INCVAL, STATE),
          begin      #{OTHER :=  VAR}         = STATE,
                STATE#{OTHER  =>  VAR + INCVAL      }
           end
          ).
          

-else.                                          % DEFAULT!
  -define(merge_with_stats(                           STATE), STATE).
  -define(update_max_qlen(           _QLEN          , STATE), STATE).
  -define(update_calls_or_casts(_CALL_OR_CAST , _INC, STATE), STATE).
  -define(update_max_time(           _TIME          , STATE), STATE).
  -define(update_other(    _OTHER ,  _VAR , _INCVAL , STATE), STATE).
-endif.


%%%-----------------------------------------------------------------
%%% These macros enable callbacks that make it possible to analyse
%%% the overload protection behaviour from outside the handler
%%% process (including dropped requests on the client side).
%%% An external callback module (?OBSERVER_MOD) is required which
%%% is not part of the kernel application. For this reason, these
%%% callbacks should not be included in code to be officially released.

%%-define(OBSERVER_MOD, logger_test).
-ifdef(   OBSERVER_MOD).
  -define(start_observation(NAME)       , ?OBSERVER:start_observation(NAME      )).
  -define(      observe     (NAME,EVENT), ?OBSERVER:observe(          NAME,EVENT)).

-else.                                          % DEFAULT!
  -define(start_observation(_NAME)        , ok).
  -define(      observe(    _NAME ,_EVENT), ok).

-endif.
%%! <---