Index: doc/Class.man =================================================================== diff -u -r2f660410f5b0bac67f2c1e7ea5e50ccab8028360 -rd4588fec011c3a8f3529ad25d3d2e033f7055b6e --- doc/Class.man (.../Class.man) (revision 2f660410f5b0bac67f2c1e7ea5e50ccab8028360) +++ doc/Class.man (.../Class.man) (revision d4588fec011c3a8f3529ad25d3d2e033f7055b6e) @@ -433,54 +433,66 @@ destruction: allocation, recreation, deallocation. [example { - [/cls/ create /instanceName/] (1) - ---------------. .----------------. - -------------->|Class->create()|-->|Class->__alloc()| - `---------------' `----------------' - | | (2) .-------------------. - | .----->|Object->configure()| - | `-------------------' - | (3) .-------------. - .........>|/cls/->init()| -[/instanceName/ destroy] `-------------' - (4) ------------------. --------------->|Class->__dealloc()| - `-----------------' + /cls/->create(/instance/) + .---------------. exists? [false] .----------------. .-------------------. + ---->|Class::create()|----><>---------------->|Class::__alloc()|-----------><>---->|Object::configure()| + `---------------' | (1) `----------------' ^ (4) `---------+---------' + [true] | | | (5) + | .-------------------. .-----------------. | .------------------. + `->|Class::__recreate()|---->|Object::cleanup()|-' |/instance/->init()| + (2) `-------------------' (3) `-----------------' `------------------' + + /instance/->destroy() + .-----------------. .------------------. + ---->|Object::destroy()|---->|Class::__dealloc()| + `-----------------' (6) `------------------' }] -The factory method [method create], provided by [cmd nx::Class] to its -instance [arg cls], produces a new object [arg instanceName] as an -instance of [arg cls] in three major steps. +Object creation is controlled by the factory method [method create], provided by [cmd nx::Class] to its +instance [arg cls]. [method create] produces a new object [arg instanceName] as an +instance of [arg cls] in a number of steps. [list_begin enumerated] -[enum] If [arg instanceName] does not represent an existing object, an -internal call to [method "__alloc"], provided by [cmd nx::Class], -creates the memory structures and, then, a raw, uninitalized instance -[arg instanceName] of [arg cls]. If [arg instanceName] corresponds to an existing object, the recreation procedure is triggered. +[enum] If [arg instance] does not represent an existing object, an +internal call to [method "__alloc"], provided by [cmd nx::Class], runs +the [emph {allocation}] procedure for a fresh [arg instance] of [arg cls]. + +[enum] If [arg instanceName] corresponds to an existing object, the +[emph {recreation}] procedure is triggered by calling [method "__recreate"] +defined by [cmd nx::Class]. -[enum] The newly allocated or recreated object [arg instanceName] is then -configured by receiving a call to [method configure], provided by [cmd nx::Object], which consumes the configuration options passed into -[method create]. This will establish the instance's initial state, -e.g., by setting object variables and object relations according to -the configuration options and corresponding default values. +[enum] Under recreation, the existing [arg instance] is resetted by calling [method cleanup]. + +[enum] The newly allocated or recreated object [arg instance] is then +configured by dispatching [method configure], provided by [cmd nx::Object], which +consumes the configuration options passed into [method create]. This +will establish the instance's initial state, e.g., by setting object +variables and object relations according to the configuration options +and corresponding default values. -[enum] [method create] then calls the initialization method [method init], if -defined. [method "init"] can be defined by [arg cls] on -behalf of its instance [arg instanceName], e.g., to lay out a +[enum] Finally, the initialization method [method init] is dispatched, if +available for [arg instance]. [method "init"] can be defined by [arg cls] on +behalf of its instance [arg instance], e.g., to lay out a class-specific initialisation behaviour. Alternatively, or additionally, the object [arg instanceName] may define an per-object [method init] on its own. [list_end] -When the destruction of an object [arg instanceName] is triggered, e.g., by an application-level [method destroy] call (4), [cmd nx::Class] manages deallocation of the object using [method __dealloc]. +Object destruction, as triggered by, e.g., an application-level +[method destroy] call (6) is finalized by [method {__dealloc}] offerd by +[cmd nx::Class]. +[para] + +In the following, the three built-in procedures --- +allocation, recreation, and deallocation --- are explained: + [list_begin itemized] -[item] [emph {Allocation}]: [method "__alloc"] creates a blank object [arg instanceName] as an instance of [arg cls] and returns the fully-qualified [arg instanceName]. [method __alloc] is primarily used internally by [method create] to allocate a Tcl memory storage for -[arg instanceName] and to register [arg instanceName] with the Tcl +[item] [emph {Allocation}]: [method "__alloc"] creates a blank object [arg instanceName] as an instance of [arg cls] and returns the fully-qualified [arg instanceName]. [method __alloc] is primarily used internally by [method create] to allocate a Tcl memory storage for [arg instanceName] and to register [arg instanceName] with the Tcl interpreter as a new command. By default, [method __alloc] is not callable as a method for clients of [arg cls]. [para] @@ -523,7 +535,6 @@ [para] - If the name conflict occurs between an existing class and a newly created object (or vice versa), recreation will not be performed. Rather, a sequence of [method destroy] and [method create] @@ -536,30 +547,25 @@ }] [para] -By default, [method __recreate] is not part of the exported method +By default, [method __recreate] is not part of the method interface of [cmd nx::Class] instances. [method __recreate] can be refined by providing an implementation of [method __recreate] in a subclass or [term "mixin class"], which can redirect to the built-in [method __recreate] using [cmd nx::next]. In the method body preceding the [cmd nx::next] call, the object under recreation has its old state, after returning from the [cmd ::nx::next], it has been -re-setted and re-configured. This way, [method __recreate] is also exported as a callable method for an instance of [cmd nx::Class]. +re-setted and re-configured. This way, [method __recreate] becomes available as a callable method for an instance of [cmd nx::Class]. [para] -[comment {Is the below still intended, currenty redefinition protection is not active on __dealloc}] As an exception, [method __recreate] for [cmd ::nx::Class] instances is protected from redefinition. Consider refining it in a subclass of [cmd ::nx::Class] or using a [term "mixin class"] for indirecting the recreation procedure. -[item] [emph {Deallocation}]: - -[arg cls] [method "__dealloc"] [arg instanceName] - -Marks an instance [arg instanceName] of [arg cls] for +[item] [emph {Deallocation}]: [method __dealloc] marks an instance [arg instance] of [arg cls] for deletion by returning its Tcl memory representation to the Tcl memory pool and by -unregistering the corresponding Tcl command from the Tcl interpreter. +unregistering the corresponding Tcl command with the Tcl interpreter. [para] @@ -572,26 +578,24 @@ [para] [method __dealloc] is primarily used internally by [method destroy]. -By default, [method __dealloc] is not part of the exported method -interface of [arg cls] instances. +By default, [method __dealloc] is not part of the method interface of +[arg cls]. [para] [method __dealloc] can be refined by providing an implementation of [method __dealloc], which can redirect to the built-in [method __dealloc] using [cmd nx::next], for the scope of [arg cls] and/or the scope of -instances of [arg cls]. This way, [method __dealloc] is also exported as -a callable method of [arg cls] instances. +instances of [arg cls]. This way, [method __dealloc] becomes available as +a callable method of [arg cls]. [para] -[comment {Is the below still intended, currenty redefinition protection is not active on __dealloc}] As an exception, [method __dealloc] for [cmd ::nx::Class] instances is protected from redefinition. Consider refining it in a subclass of [cmd ::nx::Class] or using a [term "mixin class"] for indirecting the deallocation procedure. - [list_end]