Update von efun-Manpages aus Driversourcen.
Aktualisiert manpages, welche wenig oder nicht vom
MG modifizier wurden.
Change-Id: If70b4fc27cfd38cb9e98cb48328a48731969a76f
diff --git a/doc/efun/shadow b/doc/efun/shadow
new file mode 100644
index 0000000..16ab11e
--- /dev/null
+++ b/doc/efun/shadow
@@ -0,0 +1,119 @@
+SYNOPSIS
+ object shadow(object obj, int flag)
+
+BESCHREIBUNG
+ Damit wird das aktuelle Objekt dem Objekt <obj> als Shadow
+ uebergeworfen. Bei Erfolg liefert es 1, sonst 0 zurueck.
+
+ Das aufrufende Objekt muss vom Master-Objekt die Erlaubnis haben,
+ als Shadow zu wirken. Normalerweise kann einem Objekt, das
+ query_prevent_shadow() == 1 zurueck liefert, kein Shadow
+ uebergeworfen werden. In diesem Fall liefert shadow() 0 zurueck,
+ sonst das Objekt, dem der Shadow uebergeworfen wurde.
+
+ shadow() schlaeft fehl, wenn:
+ - der Shadow vesucht, eine "nomask" definierte Funktion zu
+ ueberlagern,
+ - wenn im Praeprozessor #pragma no_shadow gesetzt ist,
+ - wenn das aufrufende Objekt bereits ein Shadow ist,
+ - wenn das aufrufende Objekt selbst einen Shadow uebergeworfen hat,
+ - wenn das aufrufende Objekt ueber ein Environment verfuegt,
+ - wenn das Zielobjekt <obj> selbst ein Shadow ist.
+
+ Wenn ein Objekt A einem Objekt B als Shadow uebergeworfen wird,
+ werden alle call_other() Aufrufe fuer B an A umgeleitet. Wenn A die
+ Funktion, die von call_other() aufgerufen wird, nicht definiert hat,
+ wird der Aufruf an B weitergeleitet. Es gibt also nur ein Objekt,
+ welches call_other() Aufrufe fuer B machen kann: das Objekt A. Nicht
+ einmal das Objekt B kann einen call_other() auf sich selbst machen.
+ Hingegen werden alle normalen (internen) Funktionsaufrufe innerhalb
+ von B werden wie gewohnt innerhalb von B bearbeitet.
+
+BEISPIELE
+ Mit drei Objekten a.c, b.c und c.c:
+
+ --- a.c ---
+ void fun() {
+ debug_message(sprintf("%O [a] fun()\n", this_object()));
+ }
+ void fun3() {
+ debug_message(sprintf("%O [a] fun3()\n", this_object()));
+ }
+
+ --- b.c ---
+ int fun() {
+ debug_message(sprintf("%O [b] fun()\n", this_object()));
+ find_object("a")->fun();
+ }
+ void fun2() {
+ debug_message(sprintf("%O [b] fun2()\n", this_object()));
+ find_object("a")->fun3();
+ this_object()->fun3();
+ }
+
+ void do_shadow(object target) { shadow(target, 1); }
+
+ --- c.c ---
+ int fun() {
+ debug_message(sprintf("%O [c] fun()\n", this_object()));
+ find_object("a")->fun();
+ }
+ void fun3() {
+ debug_message(sprintf("%O [c] fun3()\n", this_object()));
+ }
+ void do_shadow(object target) { shadow(target, 1); }
+
+ Es wird nun folgender Code aufgerufen:
+
+ object a, b, c;
+
+ a = load_object("a");
+ b = load_object("b");
+ c = load_object("c");
+ b->do_shadow(a);
+ c->do_shadow(a);
+ debug_message("--- a->fun() ---\n");
+ a->fun();
+ debug_message("--- b->fun() ---\n");
+ b->fun();
+ debug_message("--- c->fun() ---\n");
+ c->fun();
+ debug_message("--- b->fun2() ---\n");
+ b->fun2();
+
+ Das ergibt diesen Output:
+
+ --- a->fun() ---
+ /c [c] fun()
+ /b [b] fun()
+ /a [a] fun()
+ --- b->fun() ---
+ /c [c] fun()
+ /b [b] fun()
+ /a [a] fun()
+ --- c->fun() ---
+ /c [c] fun()
+ /b [b] fun()
+ /a [a] fun()
+ --- b->fun2() ---
+ /b [b] fun2()
+ /a [a] fun3()
+ /c [c] fun3()
+
+ Merke: der erste Aufruf in b::fun2() findet zuerst c::fun3()!
+ Der Grund ist, dass fuer Aufrufe aus b fuer a der Treiber
+ annimmt, dass alle Shadows vor c schon ihre Chance hatten. Der
+ zweite Aufruf hingegen ergeht an b selbst, das der Treiber als
+ vom Shadow c ueberlagert erkennt.
+
+GESCHICHTE
+ Bis 3.2.1@46 fuehrte die Zerstoerung eines Objekts, dem ein Shadow
+ uebergeworfen war, auch zur Zerstoerung aller seiner Shadows.
+ Seit 3.2.1@47 ueberleben Shadows die Zerstoerung des Objektes, dem
+ sie uebergeworfen sind (ausser, die wird von prepare_destruct()
+ manuell erledigt).
+ Seit LDMud 3.2.8 koenne sich Objekte dank #pragma no_shadow gezielt
+ davor schuetzen, einen Shadow uebergeworfen zu bekommen.
+
+SIEHE AUCH
+ query_shadowing(E), unshadow(E), query_allow_shadow(M)