[rkward-cvs] rkward/rkward/rbackend rcommand.h,1.10,1.11 rcommandstack.h,1.1,1.2

Mon Apr 18 11:19:13 UTC 2005

Update of /cvsroot/rkward/rkward/rkward/rbackend
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11357

Modified Files:
	rcommand.h rcommandstack.h 
Log Message:
Some enhancements and fixes to the API-documentation

Index: rcommand.h
===================================================================
RCS file: /cvsroot/rkward/rkward/rkward/rbackend/rcommand.h,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** rcommand.h	15 Apr 2005 13:23:13 -0000	1.10
--- rcommand.h	18 Apr 2005 11:19:11 -0000	1.11
***************
*** 36,40 ****
  	RCommandChain *parent;
  };
! /// this struct is needed by the rthread.
  class RChainOrCommand {
  private:
--- 36,42 ----
  	RCommandChain *parent;
  };
! 
! /** this struct is needed by the RCommandStrack. It is only a wrapper, which stores a pointer to _either_ a command _or_ a chain. Its sole purpose is to
! be able to insert either a command or a chain using the same mechanism, easily. You don't want to use this class outside of RCommandStack (TODO: move it to rcommandstack.h, then!) */
  class RChainOrCommand {
  private:
***************
*** 73,89 ****
  */

! /** This class is used to encapsulate an R-command, so it can be easiyl identified
  	in a chain of commands. It is needed, since communication with R is asynchronous
  	and it is therefore not possible to get the result of an R-call right away.
! 	Instead, create an object of this class, specifying the object/slot that should
  	be called when the command has finished. You can then retrieve all information
! 	on the command (including the reply) from the object that is passed to your slot.
! 	If one slot is to handle the output of several different commands, use the id ()
! 	function to keep track of the command (it returns a unique id assigned to this
! 	object).
! 	The type-parameter is used to indicate the significance of this command, and
! 	esp., whether it should be hidden from the user. (Not yet implemented)
! 	There are several ways to identify a command when it's finished:
! 		- storing the id ()
  		- passing appropriate flags to know how to handle the command
  		- keeping the pointer (CAUTION: don't use that pointer except to compare it with the pointer of an incoming command. Commands get deleted when they are finished, and maybe (in the future) if they become obsolete etc. Hence the pointers you keep may be invalid!)
--- 75,92 ----
  */

! /** This class is used to encapsulate an R-command, so it can be easily identified
  	in a chain of commands. It is needed, since communication with R is asynchronous
  	and it is therefore not possible to get the result of an R-call right away.
! 	Instead, create an object of this class, specifying the RCommandReceiver that should
  	be called when the command has finished. You can then retrieve all information
! 	on the command (including the reply) from the object that is passed to your handler.
! 	
! 	The type-parameter is used to indicate the type of command (e.g. direct User input vs. generated by a Plugin vs.
! 	command generated by the main application vs. command used merely to sync data back and forth), and also how the command
! 	should retrieve information (as a usual string, or as a data vector). @See RCommand::CommandTypes
! 	
! 	There are several ways to identify a command when it's finished (needed, if a single RCommandReceiver needs to handle the results of
! 	several different commands):
! 		- storing the id () (each command is automatically assigned a unique id, TODO: do we need this functionality? Maybe remove it for redundancy)
  		- passing appropriate flags to know how to handle the command
  		- keeping the pointer (CAUTION: don't use that pointer except to compare it with the pointer of an incoming command. Commands get deleted when they are finished, and maybe (in the future) if they become obsolete etc. Hence the pointers you keep may be invalid!)
***************
*** 132,135 ****
--- 135,139 ----
  friend class REmbed;
  friend class RInterface;
+ /// internal function will be called by the backend, as the command gets passed through. Takes care of sending this command (back) to its receiver
  	void finished ();
  	QString _output;

Index: rcommandstack.h
===================================================================
RCS file: /cvsroot/rkward/rkward/rkward/rbackend/rcommandstack.h,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** rcommandstack.h	7 Sep 2004 13:45:24 -0000	1.1
--- rcommandstack.h	18 Apr 2005 11:19:11 -0000	1.2
***************
*** 33,48 ****
  	~RCommandStack ();

  	static void issueCommand (RCommand *command, RCommandChain *chain);
! 	
  	static RCommandChain *startChain (RCommandChain *parent);
  	static RCommandChain *closeChain (RCommandChain *chain);

  	bool isEmpty ();
  	bool isBlocked ();
  	bool isActive ();
! 	
  	RCommand *pop ();
! 	
  	static RCommandStack *regular_stack;
  	static RCommandStack *chainStack (RCommandChain *child);
  private:
--- 33,58 ----
  	~RCommandStack ();

+ /// add a command to the given chain (static, as it does no matter, which stack the chain belongs to)
  	static void issueCommand (RCommand *command, RCommandChain *chain);
! 
! /// add a sub-chain to the given chain (static, as it does no matter, which stack the chain belongs to)
  	static RCommandChain *startChain (RCommandChain *parent);
+ /** close the given chain, i.e. signal the chain may be deleted once its remaining commands are done
+  (static, as it does no matter, which stack the chain belongs to).  @Returns the parent of the closed chain. */
  	static RCommandChain *closeChain (RCommandChain *chain);

+ /// @Returns true, if there are no commands or open chains waiting in this stack
  	bool isEmpty ();
+ /// @Returns true, if the currently processed chain is not closed and not empty
  	bool isBlocked ();
+ /// @Returns true, if there are commands to be processed in the current chain
  	bool isActive ();
! 
! /// removes the RCommand to be processed next from the stack and returns it. If there is no command to process right now, returns 0
  	RCommand *pop ();
! 
! /// the regular command stack, i.e. not a callback
  	static RCommandStack *regular_stack;
+ /// return the parent RCommandStack of the given RCommandChain
  	static RCommandStack *chainStack (RCommandChain *child);
  private: