fix a few typos and add some additional api ideas

1 files changed, 31 insertions, 14 deletions

diff --git a/KEEPING-PROGRAMS-LINEAR b/KEEPING-PROGRAMS-LINEAR
index 224187c..1fa7e40 100644
--- a/KEEPING-PROGRAMS-LINEAR
+++ b/KEEPING-PROGRAMS-LINEAR
@@ -13,11 +13,11 @@ do_a_third_operation ()
 
 has to be factored into a non-linear program, where one operation is
 requested and the reply is waited for in the event loop then on reply
-the next operation is requested and so one.
+the next operation is requested and so on. 
 
 I guess the goal should be come up with an api that makes a
 program as simple as or nearly as simple as the above but still
-returns to the event loop between steps.
+returns to the event loop between and during steps.
 
 Maybe something like:
 
@@ -72,8 +72,9 @@ transaction_commit ()
 Where transaction_state_data would encode the current state of
 the transaction along with an transaction specific data.  The
 problem with this approach is their is a lot of redundancy.  We
-want the same data available from every action along the way, so
-we should only have to specify it at most once.
+want the same data available from every action along the way, so later
+actions can read data set by earlier actions.  Since we want it throughout
+the transaction we should only have to specify that data at most once.
 
 Another idea might be something like:
 
@@ -83,7 +84,7 @@ transaction_add_action (transaction, do_another_operation)
 transaction_add_action (transaction, do_a_third_operation)
 transaction_commit ()
 
-and then could pass the state data to each action automatically
+and we then could pass the state data to each action automatically
 or via an accessor function on the transaction object.  A
 problem with this approach (and the approach before this one) is
 it enforces a tight binding between all the actions in the
@@ -94,10 +95,11 @@ coupled to its transaction.  This is undesirable because an
 action really only cares about the state data it's operating on.
 It only needs to "know" about the data it depends on and on the
 data its outputing for later actions to use.  By limiting the
-data available to an action we can make sure that it is usable
-in multiple transactions.
+data available to an action, we make the action more primitive.
+In other words, we can make sure that it is usable in different
+situations, for multiple independent transactions.
 
-One way to do this, at the loss of type safety, is make
+One way to do this, at the loss of type safety, is to make
 transaction_state_data be a generic container type like a
 GHashTable.  An action would then rely on certain named keys
 being set to do its work and would set other named keys for
@@ -122,7 +124,7 @@ cleaned up automatically when the transaction finishes or is
 explicitly removed from the transaction object with
 delete_state_data.
 
-Another important consideration is that actions need to only
+Another important consideration is that actions should only
 chip away at a problem, not block.  So they will need to be
 invoked multiple times and notify the transaction when they are
 done.  Each action handler could return one of three possible
@@ -134,11 +136,11 @@ SUCCEEDED
 
 If an action isn't finished it will be called again until it is
 finished.  If an action fails, then the whole transaction fails
-and all state is cleaned up.  If it succeed, the whole
-transaction succeeds and all state is cleaned up.
+and all state is cleaned up.  If it succeeds, the transaction 
+transitions to the next action.
 
 In either the failed or success cases, there should probably be
-a handler invoked to note that the transaction has finished.
+a handler invoked to note when the transaction has finished.
 The handler should get passed the transaction state.
 
 Other thoughts...
@@ -166,8 +168,23 @@ enforce the state directly in the pause call.
 transaction_pause_for_fd (transaction, "my-action-fd", fd, G_IO_READ, close_fd)
 
 We should post a g_warning if a transaction is pausing on more
-than fd also.
+than one fd also.
+
+There are other types of things to wait on that would probably
+be useful to add to the api.  For instance, 
+
+void transaction_pause_for_a_while ((Transaction *transaction, guint a_while);
+
+And another one that might be convenient:
+
+void transaction_pause_for_source (Transaction *transaction, GSource *source)
+
+The last one could serve as an implementation detail of the
+other two and also allow apps to block on other interesting
+events like child termination, etc.
 
 Another interesting point is actions may sometimes be compound.
 In those cases it might be useful to allow an action to prepend
-actions before it in the queue.
+actions before it in the queue.  Perhaps something like:
+
+transaction_add_action (transaction, do_another_operation_first)