mirror of
https://github.com/git/git
synced 2024-10-30 04:01:21 +00:00
3891a84ccd
Evaluating the script in the same namespace as the chord itself creates potential for variable name collision. And in that case the script would unknowingly use the chord's variables. For example, say the script has a variable called 'is_completed', which also exists in the chord's namespace. The script then calls 'eval' and sets 'is_completed' to 1 thinking it is setting its own variable, completely unaware of how the chord works behind the scenes. This leads to the chord never actually executing because it sees 'is_completed' as true and thinks it has already completed. Avoid the potential collision by creating a separate namespace for the script that is a child of the chord's namespace. Signed-off-by: Pratyush Yadav <me@yadavpratyush.com>
158 lines
5.3 KiB
Tcl
158 lines
5.3 KiB
Tcl
# Simple Chord for Tcl
|
|
#
|
|
# A "chord" is a method with more than one entrypoint and only one body, such
|
|
# that the body runs only once all the entrypoints have been called by
|
|
# different asynchronous tasks. In this implementation, the chord is defined
|
|
# dynamically for each invocation. A SimpleChord object is created, supplying
|
|
# body script to be run when the chord is completed, and then one or more notes
|
|
# are added to the chord. Each note can be called like a proc, and returns
|
|
# immediately if the chord isn't yet complete. When the last remaining note is
|
|
# called, the body runs before the note returns.
|
|
#
|
|
# The SimpleChord class has a constructor that takes the body script, and a
|
|
# method add_note that returns a note object. Since the body script does not
|
|
# run in the context of the procedure that defined it, a mechanism is provided
|
|
# for injecting variables into the chord for use by the body script. The
|
|
# activation of a note is idempotent; multiple calls have the same effect as
|
|
# a simple call.
|
|
#
|
|
# If you are invoking asynchronous operations with chord notes as completion
|
|
# callbacks, and there is a possibility that earlier operations could complete
|
|
# before later ones are started, it is a good practice to create a "common"
|
|
# note on the chord that prevents it from being complete until you're certain
|
|
# you've added all the notes you need.
|
|
#
|
|
# Example:
|
|
#
|
|
# # Turn off the UI while running a couple of async operations.
|
|
# lock_ui
|
|
#
|
|
# set chord [SimpleChord::new {
|
|
# unlock_ui
|
|
# # Note: $notice here is not referenced in the calling scope
|
|
# if {$notice} { info_popup $notice }
|
|
# }
|
|
#
|
|
# # Configure a note to keep the chord from completing until
|
|
# # all operations have been initiated.
|
|
# set common_note [$chord add_note]
|
|
#
|
|
# # Activate notes in 'after' callbacks to other operations
|
|
# set newnote [$chord add_note]
|
|
# async_operation $args [list $newnote activate]
|
|
#
|
|
# # Communicate with the chord body
|
|
# if {$condition} {
|
|
# # This sets $notice in the same context that the chord body runs in.
|
|
# $chord eval { set notice "Something interesting" }
|
|
# }
|
|
#
|
|
# # Activate the common note, making the chord eligible to complete
|
|
# $common_note activate
|
|
#
|
|
# At this point, the chord will complete at some unknown point in the future.
|
|
# The common note might have been the first note activated, or the async
|
|
# operations might have completed synchronously and the common note is the
|
|
# last one, completing the chord before this code finishes, or anything in
|
|
# between. The purpose of the chord is to not have to worry about the order.
|
|
|
|
# SimpleChord class:
|
|
# Represents a procedure that conceptually has multiple entrypoints that must
|
|
# all be called before the procedure executes. Each entrypoint is called a
|
|
# "note". The chord is only "completed" when all the notes are "activated".
|
|
class SimpleChord {
|
|
field notes
|
|
field body
|
|
field is_completed
|
|
field eval_ns
|
|
|
|
# Constructor:
|
|
# set chord [SimpleChord::new {body}]
|
|
# Creates a new chord object with the specified body script. The
|
|
# body script is evaluated at most once, when a note is activated
|
|
# and the chord has no other non-activated notes.
|
|
constructor new {i_body} {
|
|
set notes [list]
|
|
set body $i_body
|
|
set is_completed 0
|
|
set eval_ns "[namespace qualifiers $this]::eval"
|
|
return $this
|
|
}
|
|
|
|
# Method:
|
|
# $chord eval {script}
|
|
# Runs the specified script in the same context (namespace) in which
|
|
# the chord body will be evaluated. This can be used to set variable
|
|
# values for the chord body to use.
|
|
method eval {script} {
|
|
namespace eval $eval_ns $script
|
|
}
|
|
|
|
# Method:
|
|
# set note [$chord add_note]
|
|
# Adds a new note to the chord, an instance of ChordNote. Raises an
|
|
# error if the chord is already completed, otherwise the chord is
|
|
# updated so that the new note must also be activated before the
|
|
# body is evaluated.
|
|
method add_note {} {
|
|
if {$is_completed} { error "Cannot add a note to a completed chord" }
|
|
|
|
set note [ChordNote::new $this]
|
|
|
|
lappend notes $note
|
|
|
|
return $note
|
|
}
|
|
|
|
# This method is for internal use only and is intentionally undocumented.
|
|
method notify_note_activation {} {
|
|
if {!$is_completed} {
|
|
foreach note $notes {
|
|
if {![$note is_activated]} { return }
|
|
}
|
|
|
|
set is_completed 1
|
|
|
|
namespace eval $eval_ns $body
|
|
delete_this
|
|
}
|
|
}
|
|
}
|
|
|
|
# ChordNote class:
|
|
# Represents a note within a chord, providing a way to activate it. When the
|
|
# final note of the chord is activated (this can be any note in the chord,
|
|
# with all other notes already previously activated in any order), the chord's
|
|
# body is evaluated.
|
|
class ChordNote {
|
|
field chord
|
|
field is_activated
|
|
|
|
# Constructor:
|
|
# Instances of ChordNote are created internally by calling add_note on
|
|
# SimpleChord objects.
|
|
constructor new {c} {
|
|
set chord $c
|
|
set is_activated 0
|
|
return $this
|
|
}
|
|
|
|
# Method:
|
|
# [$note is_activated]
|
|
# Returns true if this note has already been activated.
|
|
method is_activated {} {
|
|
return $is_activated
|
|
}
|
|
|
|
# Method:
|
|
# $note activate
|
|
# Activates the note, if it has not already been activated, and
|
|
# completes the chord if there are no other notes awaiting
|
|
# activation. Subsequent calls will have no further effect.
|
|
method activate {} {
|
|
if {!$is_activated} {
|
|
set is_activated 1
|
|
$chord notify_note_activation
|
|
}
|
|
}
|
|
}
|