Gesammelte Doku-Update unbekannter Herkunft
Mal wieder ein Sammel-Commit von Dingen, die niemand
committet hat.
Change-Id: I6564091f0f3c0a708247c85973bfcf5c0e23f1da
diff --git a/doc/lfun/clean_up b/doc/lfun/clean_up
index 7c124fb..c1bf14e 100644
--- a/doc/lfun/clean_up
+++ b/doc/lfun/clean_up
@@ -12,56 +12,97 @@
DEFINIERT IN
============
- /std/room.c
- man kann die Funktion jedoch auch in beliebigen Objekten selbst
- definieren.
+ * /std/room.c
+
+ * man kann die Funktion jedoch auch in beliebigen Objekten selbst
+ definieren.
ARGUMENTE
=========
ref
- + 0 bei gecloneten Objekten
- + 1 bei einfachen geladenen Objekten
- + >1 bei Objekten, die geerbt wurden oder als Blueprint dienen
- + <0, wenn clean_up() von aussen aufgerufen wurde (das muss man
- selbst beachten!)
+ Ein Referenzzaehler (s.u.)
BESCHREIBUNG
============
- Wenn ein Objekt seit langer Zeit nicht mehr benutzt wurde, kann es sich
- hier selbst zerstoeren. Das sollte das Objekt allerdings nur tun, wenn
- ref kleiner oder gleich 1 ist.
+ Wenn ein Objekt seit langer Zeit nicht mehr benutzt wurde (d.h. es
+ wurde keine lfun *von aussen* in ihm gerufen), ruft der Driver
+ diese Funktion auf. Es kann es sich hier selbst zerstoeren, um
+ Speicher freizugeben (und ggf. spaeter mit aktuellem Sourcecode neu
+ erzeugt werden, was auch eine Art einfacher Updatemechanismus ist).
+
+ Der Referenzzaehler <ref> gibt an, wie oft das Objekt als Vorlage
+ fuer Clones oder erbende Programme dient. Folgende Faelle sind
+ damit unterscheidbar:
+
+ ref==0:
+ Das Objekt ist ein Clone (oder eine Blueprint mit ersetztem
+ Programm)
+
+ ref==1:
+ Das Objekt ist eine Blueprint (kein Clone), von welcher zur
+ Zeit keine Clones oder erbenden Programme existieren.
+
+ ref > 1:
+ Das Objekt dient als Vorlage / Blueprint fuer Clones oder
+ erbende Programme.
+
+ Das Objekt im clean_up zu zerstoeren, ist in der Regel ist daher
+ nur sinnvoll, wenn ref kleiner oder gleich 1 ist.
+
+ Sollte man einem Objekt ein clean_up geben, was als Clone im Umlauf
+ ist und dieses im Falle von ref==0 zerstoeren, bedeutet dies
+ letztendlich, dass sich ungenutzte Clones aufraeumen.
+
+ In einem Spezialfall kann ref auch < 0 sein: wenn clean_up *nicht*
+ vom Driver gerufen wird, sondern (manuell) von irgendwo aus der
+ Mudlib, ist die *Konvention*, einen Wert < 0 zu uebergeben.
+
+ Standardmaessig definieren nur Raeume clean_up(). Hierbei gilt die
+ Besonderheit, dass Raeume sich erst beim *zweiten* Aufruf von
+ clean_up() wegraeumen, wenn in ihnen Objekte liegen, die der Raum
+ *nicht* selbst mittels AddItem() erzeugt hat. D.h. laesst jemand
+ etwas im Raum rumliegen, erhoeht sich effektiv die Cleanup-Zeit auf
+ das doppelte. Und hat irgendjemand sich auf einen Hook des Raums
+ registriert, raeumt der Raum sich nicht im clean_up() auf.
+
+ Soll ein Raum sich niemals per clean_up() selber aufraeumen, kann
+ die Property P_NEVER_CLEAN gesetzt werden. Aber bitte seid hiermit
+ *sehr sparsam* und benutzt das nur in Raeumen, die es wirklich
+ benoetigen. Fast alle Raeume kommen super klar, wenn sie bei Bedarf
+ neu erzeugt werden.
RUeCKGABEWERT
=============
Der Rueckgabewert hat nur dann eine Bedeutung, wenn sich das Objekt
- nicht selbst zerstoert hat. Wird 0 zurueckgegeben, so wird clean_up()
- erst dann wieder aufgerufen, nachdem das Objekt aus- und wieder
- eingeswappt wurde.
+ nicht selbst zerstoert hat.
- Ein Rueckgabewert ungleich 0 zeigt an, dass das Objekt sich
- wahrscheinlich in der naechsten clean_up()-Runde zerstoeren kann, wenn
- in der Zwischenzeit zB. noch einmal reset() aufgerufen wurde.
+ Wird 0 zurueckgegeben, so wird clean_up() *nicht erneut* gerufen.
+ Ein Rueckgabewert ungleich 0 zeigt hingegen an, dass das Objekt
+ sich moeglicherweise beim naechsten Aufruf von clean_up()
+ zerstoeren koennte, d.h. der Driver wird es nach Ablauf der
+ Cleanup-Zeit erneut versuchen.
BEMERKUNGEN
===========
- Standardmaessig definieren nur Raeume clean_up().
-
- Die Zeiten zwischen zwei Aufrufen von clean_up() betragen momentan
- einen Tag (86400 Sekunden).
+ Die Cleanup-Zeit, die ein Objekt nicht benutzt werden darf, bevor
+ clean_up() aufgerufen wird, betraegt momentan 18h (64800 Sekunden).
SIEHE AUCH
==========
- reset(), P_NEVER_CLEAN
- memory
+ lfuns:
+ reset()
-21. Maerz 2004 Gloinson
+ Properties:
+ P_NEVER_CLEAN
+
+18.02.2019, Zesstra