sigc++/doc/marshal

   1
   2 1.0 Marshallers
   3 ===============
   4
   5 Marshallers offer the opportunity to control the emittion process, and
   6 collate return values. By default signals have a marshaller which does
   7 nothing, and throws away all but the last return value.
   8
   9 A marshaller can be any class with:
  10   struct  SomeMarshal
  11     {
  12        // both typedefs must be defined.
  13        typedef Type1 InType;
  14        typedef Type2 OutType;
  15
  16        // Return final return code.
  17        OutType value();
  18
  19        // Return value if marshaller does not get built
  20        static OutType default_value();
  21
  22        // Captures return codes and returns TRUE to stop emittion.
  23        bool marshal(const InType&);
  24
  25        SomeMarshal();
  26    };
  27
  28 The function marshal() will be called with the return value of each slot
  29 connected to the signal as they are called. The emittion process can be
  30 stopped by marshal() returning true.
  31
  32 Once all the slots have been called, value() is called to determine what
  33 to return to the emitter.  If the signal gets called and there is
  34 nothing attached the default_value() is used.
  35
  36 2.0 Possible uses
  37 =================
  38 A marshaller could stop emittion when the signal had been handled:
  39   struct StopOnTrue
  40     {
  41       typedef bool InType;
  42       typedef bool OutType;
  43       OutType  return_value_;
  44
  45       OutType value() { return return_value_; }
  46       static OutType default_value() { return false; }
  47       bool marshal(const InType& val) { return_value_ = val; return val; }
  48
  49       StopOnTrue() : return_value_(false) {}
  50     };
  51
  52 marshal() here returns true as soon as one of the things connected to the
  53 signal returns true. It also keeps track of whether anything stopped the
  54 emittion in the return_value_ member. This way when something emits the
  55 signal, it can tell whether the signal was dealt with (signal.emit()
  56 returns true) or not (signal.emit() returns false).
  57
  58 Now, if OutType was a list or a vector, marshal() could push_back() all
  59 the values, returning to the emitter all the return values rather than just
  60 one.
  61
  62 3.0 Standard Marshallers
  63 ========================
  64
  65 The following marshallers are provided by default.
  66
  67   Marshal<void>
  68   Marshal<T>
  69   Marshal<R>  (untested, may not be portable)
  70   FixedMarshal<T,V>
  71   FastMarshal<T>
  72
  73 where
  74  -  T can be a type, class, or pointer
  75  -  R can be a reference
  76  -  V is the initial value of the marshaller
  77     which is returned if nothing is connected.
  78
  79 All of the standard defined marshallers, with the exception of
  80 FastMarshal,  check for a possiblity of a skipped return code via
  81 RetCode::check_ignore().  You can cause a return code to be
  82 ignored by the marshaller by setting RetCode::ignore() prior to returning
  83 to a function.  Please note that you must be sure that you are returning to
  84 signal call to use ignore().  Calling at other times may result in other
  85 functions incorrectly skipping.
  86
  87 The check_ignore function is thread safe which may induce
  88 unnecessary delays in slot calling.  To avoid this overhead
  89 either define the signal to have a void return or
  90 use a FastMarshal.
  91
  92 (This will all be replaced by an exeption mechanism at some point;
  93 however, current compiler technology is too slow for this to
  94 work.)
  95