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