cpf_register_callback

CPF_REGISTER_CALLBACK  Register CPF callback functions
   CPF_CALLBACKS = CPF_REGISTER_CALLBACK(CPF_CALLBACKS, FCN, PRIORITY)

   Registers a CPF callback function to be called by RUNCPF.

   Inputs:
       CPF_CALLBACKS : struct containing info about registered CPF
                       callback fcns
       FCN : string containing name of callback function
       PRIORITY : number that determines order of execution for multiple
                  callback functions, where higher numbers run first,
                  default priority is 20, where the standard callbacks
                  are called with the following priority:
                       cpf_flim_event_cb       53
                       cpf_vlim_event_cb       52
                       cpf_nose_event_cb       51
                       cpf_target_lam_event_cb 50
                       cpf_qlim_event_cb       41
                       cpf_plim_event_cb       40
                       cpf_default_callback    0
^      ARGS : arguments to be passed to the callback each time it is invoked

   Outputs:
       CPF_CALLBACKS : updated struct containing info about registered
                       CPF callback fcns

   User Defined CPF Callback Functions:
       The user can define their own callback functions which take
       the same form and are called in the same contexts as
       CPF_DEFAULT_CALLBACK. These are specified via the MATPOWER
       option 'cpf.user_callback'. This option can be a string containing
       the name of the callback function, or a struct with the following
       fields, where all but the first are optional:
           'fcn'       - string with name of callback function
           'priority'  - numerical value specifying callback priority
                (default = 20, see CPF_REGISTER_CALLBACK for details)
           'args'      - arbitrary value (any type) passed to the callback
                         as CB_ARGS each time it is invoked
       Multiple user callbacks can be registered by assigning a cell array
       of such strings and/or structs to the 'cpf.user_callback' option.

   See also RUNCPF, CPF_DEFAULT_CALLBACK.

0001 function cpf_callbacks = cpf_register_callback(cpf_callbacks, fcn, priority, args)
0002 %CPF_REGISTER_CALLBACK  Register CPF callback functions
0003 %   CPF_CALLBACKS = CPF_REGISTER_CALLBACK(CPF_CALLBACKS, FCN, PRIORITY)
0004 %
0005 %   Registers a CPF callback function to be called by RUNCPF.
0006 %
0007 %   Inputs:
0008 %       CPF_CALLBACKS : struct containing info about registered CPF
0009 %                       callback fcns
0010 %       FCN : string containing name of callback function
0011 %       PRIORITY : number that determines order of execution for multiple
0012 %                  callback functions, where higher numbers run first,
0013 %                  default priority is 20, where the standard callbacks
0014 %                  are called with the following priority:
0015 %                       cpf_flim_event_cb       53
0016 %                       cpf_vlim_event_cb       52
0017 %                       cpf_nose_event_cb       51
0018 %                       cpf_target_lam_event_cb 50
0019 %                       cpf_qlim_event_cb       41
0020 %                       cpf_plim_event_cb       40
0021 %                       cpf_default_callback    0
0022 %^      ARGS : arguments to be passed to the callback each time it is invoked
0023 %
0024 %   Outputs:
0025 %       CPF_CALLBACKS : updated struct containing info about registered
0026 %                       CPF callback fcns
0027 %
0028 %   User Defined CPF Callback Functions:
0029 %       The user can define their own callback functions which take
0030 %       the same form and are called in the same contexts as
0031 %       CPF_DEFAULT_CALLBACK. These are specified via the MATPOWER
0032 %       option 'cpf.user_callback'. This option can be a string containing
0033 %       the name of the callback function, or a struct with the following
0034 %       fields, where all but the first are optional:
0035 %           'fcn'       - string with name of callback function
0036 %           'priority'  - numerical value specifying callback priority
0037 %                (default = 20, see CPF_REGISTER_CALLBACK for details)
0038 %           'args'      - arbitrary value (any type) passed to the callback
0039 %                         as CB_ARGS each time it is invoked
0040 %       Multiple user callbacks can be registered by assigning a cell array
0041 %       of such strings and/or structs to the 'cpf.user_callback' option.
0042 %
0043 %   See also RUNCPF, CPF_DEFAULT_CALLBACK.
0044 
0045 %   MATPOWER
0046 %   Copyright (c) 2016, Power Systems Engineering Research Center (PSERC)
0047 %   by Ray Zimmerman, PSERC Cornell
0048 %   and Shrirang Abhyankar, Argonne National Laboratory
0049 %
0050 %   This file is part of MATPOWER.
0051 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0052 %   See https://matpower.org for more info.
0053 
0054 %% default priority
0055 if nargin < 4
0056     args = [];
0057     if nargin < 3
0058         priority = [];
0059     end
0060 end
0061 if isempty(priority)
0062     priority = 20;
0063 end
0064 
0065 cb = struct( ...
0066         'fcn', fcn, ...
0067         'priority', priority, ...
0068         'args', args ...
0069     );
0070 if ~isa(cb.fcn, 'function_handle')
0071     cb.fcn = str2func(cb.fcn);
0072 end
0073 
0074 %% add it to the list
0075 if isempty(cpf_callbacks)
0076     cpf_callbacks = cb;         %% first one
0077 else
0078     ncb = length(cpf_callbacks) + 1;
0079     cpf_callbacks(ncb) = cb;    %% append
0080     
0081     %% sort by descending priority
0082     p = cell(ncb, 1);
0083     [p{:}] = deal(cpf_callbacks.priority);
0084     [junk, i] = sort(cell2mat(p), 'descend');
0085     cpf_callbacks = cpf_callbacks(i);
0086 end