Proposal for thread-safe interface to Octave internals

[John Swensen]

One of attached files is a header file for a proposed method of allowing
external/add-on applications (e.g. Octave Workshop or the GTK UI I am
working on) to have access to various Octave internal data in a
thread-safe manner.  It allows Octave to push data into mutex protected
buffers at appropriate times for subsequent retrieval by some other thread.

The two places I identified as ideal for exporting this data are:
   src/toplev.cc - In the main_loop() function just prior to the end of
the do..while loop
   src/pt-bp.h    - In the MAYBE_DO_BREAKPOINT macro just prior to the
do_keyboard() call

The other file is a proposed ICD for communicating with this server over
a TCP connection.  It is preliminary, but I think I have defined all the
core functionality, just not the specifics of the payload format.

I would like comments on both of them and the option of jwe and the
other core maintainers as to whether you would be willing to include
this in the core distribution.

John Swensen

/*
 *
 * Copyright (C) 2006 John P. Swensen
 *
 * This file is proposed as a part of Octave.
 *
 * Octave is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2, or (at your option) any
 * later version.
 *
 * Octave is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Octave; see the file COPYING.  If not, write to the Free
 * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 * 02110-1301, USA.
 *
 * */

#if !defined (octave_server_h)
#define octave_server_h 1

#include <cstdio>
#include <string>
#include <vector>

typedef int status_t;

/**
 * Enumeration used to identify breakpoint actions
 */
typedef enum bp_action_enum
{
  BP_ACTION_NONE        = 0,
  BP_ACTION_STEP_INTO   = 1,
  BP_ACTION_STEP_OVER   = 2,
  BP_ACTION_CONTINUE    = 3,
  BP_ACTION_BREAK       = 4,
} bp_action_t;

/**
 * Structure used to store breakpoint info.
 *
 * Notes: used for add, remove, list operations, as well as for the 
BreakpointReached event.
 */
typedef struct bp_info_struct
{
  /**
   * The full path and filename where the breakpoint resides.
   */
  std::string filename;   

  /**
   * The line number where the breakpoint resides.
   * In the future, -1 can indicate an existing but disabled breakpoint.  This
   * assumes that no one will ever have an M file longer than 2Million lines.
   */
  int line_number;
} bp_info_t;

/**
 * Structure used to store variable information similar to that returned by
 * the 'whos' function.
 */
typedef struct variable_info_struct
{
  /**
   * The name of the variable
   */
  std::string variable_name;

  /**
   * The dimensional size of the variable.
   */
  std::vector<int> size;

  /**
   * The size of the variable in bytes.
   */
  unsigned long long byte_size;

  /**
   * The name of the variable type.
   */
  std::string type_name;
  
} variable_info_t;


class octave_server
{
  private:
    /**
     * Mutex variable used to protect access to internal class data.
     */
    pthread_mutex_t server_mutex;
          
          
    /***********************************************************************
     * DEBUGGING RELATED VARIABLE
     **********************************************************************/
    std::vector<bp_info_t> current_breakpoints;
    std::vector<bp_info_t> breakpoint_reached;
    std::vector<bp_info_t> added_breakpoints;
    std::vector<bp_info_t> removed_breakpoint;
    std::vector<bp_info_t> modify_breakpoints_old;
    std::vector<bp_info_t> modify_breakpoints_new;
    bp_action_t            bp_action;
   
    /***********************************************************************
     * VARIABLE INTERROGATION RELATED VARIABLES
     **********************************************************************/
    std::vector<variable_info_t> variable_symtab_list;
    std::vector<std::string>     variables_request_list;

    // NOTE: Create an overloaded operator<< for octave_value to do the
    // flattening.  This will allow us to append easily to an ostringstream
    // for output.
    std::vector<octave_value>    requested_variables;    
    
  public:
    octave_server( bool startTcpServer = false );
    ~octave_server();

    /**
     * FUNCTION USED ONLY WHEN THE TCP SERVER IS RUNNING
     */
    void process_disconnect();
    void process_accept();
    uint8* recvMessage();
    status_t sendMessage( uint8* buffer );

    static status_t ThreadFunc( octave_server* server );
    
    /*****************************************************
     * FUNCTIONS USED TO ACCESS DATA FROM THE SERVER SIDE
     *****************************************************/

    /**
     * Calls all the appropriate functions that follow to send requested
     * data from Octave to the client in a thread-safe manner.  Since this
     * will most likely only be used for the socket version of the server,
     * each individual function must perform locking to access the data in
     * a thread-safe manner (e.g. Octave Workshop may call these directly).
     * 
     * Algorithm:
     *   Call all functions
     **/
    status_t process_octave_internals_data(void);
   
    /***********************************************************************
     * DEBUGGING RELATED FUNCTIONS
     **********************************************************************/ 
    std::vector<bp_info_t> get_breakpoint_list();
    std::vector<bp_info_t> get_breakpoint_reached();    
    status_t               add_breakpoint( bp_info_t bp_info );
    status_t               remove_breakpoint( bp_info_t bp_info );
    status_t               modify_breakpoint( bp_info_t old_bp_info, bp_info_t 
new_bp_info );
    status_t               set_breakpoint_action( bp_action_t action );
   
    /***********************************************************************
     * VARIABLES RELATED FUNCTIONS
     **********************************************************************/
    std::vector<variable_info_t>        get_variable_info_list(void);
    std::vector<octave_value>           get_requested_variables_values(void);
    status_t                            set_requested_variables_names( 
std::vector<std::string> variable_names );

    /***********************************************************************
     * HISTORY RELATED FUNCTIONS
     **********************************************************************/
    std::vector<std::string>    get_history_list(void);
    
    /*************************************************************************
     * FUNCTIONS USED TO ACCESS DATA FROM THE OCTAVE SIDE
     *
     * NOTE: THIS IMPLIES THAT THESE ARE ONLY CALLED FROM
     * OCTAVE DURING A TIME IN WHICH THINGS ARE KNOWN TO
     * BE "THREAD-SAFE".  PROPOSED LOCATIONS:
     *     src/toplev.cc - main_loop() at the end of the do...while
     *     src/pt-bp.h   - MAYBE_DO_BREAKPOINT just prior to the do_keyboard
     * Most of these will call octave API functions to "pull" the data, rather
     * than having octave pass in the data.  This will help make changes 
     * exlusive to this class if/when the Octave API changes.
     *************************************************************************/
    
    /**
     * Calls all the appropriate functions that follow to update Octave
     * according to the data sent from the client in a thread-safe manner.
     *
     * Algorithm:
     *   Acquire lock
     *   process_breakpoint_add_remove_modify
     *   set_current_breakpoint
     *   set_breakpoint_list
     *   ...
     *   Release lock
     */
    status_t process_octave_server_data(void);
 
    /***********************************************************************
     * DEBUGGING RELATED FUNCTIONS
     **********************************************************************/   
    status_t set_breakpoint_list(void);
    status_t set_current_breakpoint(string filename, int line_number); // 
duplicate of process_breakpoint_action or helper function???
    status_t process_breakpoint_add_remove_modify(void);
    status_t process_breakpoint_action(void);

    /***********************************************************************
     * VARIABLES INTERROGATION RELATED FUNCTIONS
     **********************************************************************/
    status_t set_variable_info_list(void);
    status_t process_requested_variables(void);
    
    /***********************************************************************
     * HISTORY RELATED FUNCTIONS
     **********************************************************************/    
    status_t set_initial_history_list(void);
    status_t append_history(void);
};


#endif // octave_server_h

OctaveUiICD.ods
Description: application/vnd.oasis.opendocument.spreadsheet