libzypp: zypp::callback Namespace Reference

libzypp 17.25.10

Classes
zypp::callback Namespace Reference

Callbacks light. More...

## Classes
struct | DistributeReport
struct | ReceiveReport
struct | ReportBase
struct | SendReport
struct | TempConnect
| Temporarily connect a ReceiveReport then restore the previous one. More...
class | UserData
| Typesafe passing of user data via callbacks. More...

## Detailed Description

Callbacks light.

The task report structure (SENDER SIDE).

A default constructible struct derived from callback::ReportBase. It must not contain any data, just virtual methods.

These are the functions the sender invokes, and which will be forwarded to some receiver. If no receiver is present, the defined default implementations are invoked.

For methods returning non-void, define a reasonable return value, because this is what you get back in case no receiver is listening.

That way the sending side does not need to know whether some receiver is listening. And it enables the receiver to return a reasonable value, in case he's got no idea, what else to return.

struct Foo : public callback::ReportBase
{
virtual void ping( int i )
{}
virtual int pong()
{ return -1; }
};
zypp::callback::ReportBase
Definition: Callback.h:150

Sending a Task report (SENDER SIDE).

Simply create a callback::SendReport<TReport>, where TReport is your task report structure. Invoke the callback functions as needed. That's it.

Note
  Even creation and destruction of a callback::SendReport are indicated to a receiver. So even in case of an Exception, the receiver is able to recognize, that the task ended. So don't create it without need.

{
callback::SendReport<Foo> report;
report->ping( 13 );
int response = report->pong();
}
report
callback::SendReport< DownloadProgressReport > * report
Definition: MediaCurl.cc:70
zypp::callback::SendReport
Definition: Callback.h:237

Receiving Task reports (RECEIVER SIDE).

To receive task reports of type `Foo` the recipient class derives from callback::ReceiveReport<Foo>. callback::ReceiveReport inherits `Foo` and provides two additional virtual methods:

virtual void reportbegin() {}
virtual void reportend() {}

These two are automatically invoked, whenever the sender creates a callback::SendReport instance, and when it gets destructed. So even if the sending task is aborted without sending an explicit notification, the reciever may notice it, by overloading `reportend`.

Overload the methods you're interested in.

Note
  In case you must return some value and don't know which, return the task structures default. The author of the task structure had to provide this value, so it's probabely better than anything you invent.
  int somefunction()
  {
  ...// don't know what to return?
  return Foo::somefunction();
  }

Connecting the Receiver

For this callback::ReceiveReport provides 4 methods:

void connect();
void disconnect();
bool connected() const;
ReceiveReport * whoIsConnected() const;
zypp::callback::ReceiveReport
Definition: Callback.h:169

- `connect` Connect this ReceiveReport (in case some other ReceiveReport is connected, it get disconnected. Remember its a Callback light).
- `disconnect` Disconnect this ReceiveReport in case it is connected. If not connected nothing happens.
- `connected` Test whether this ReceiveReport is currently connected.
- `whoIsConnected` Return a 'ReceiveReport*' to the currently connected ReceiveReport, or `NULL` if none is connected.

Passing Userdata via Callbacks

For typesafe passing of user data via callbacks

See also
  UserData.

ReportBase provides a generic callback::ReportBase:report method which can be used to communicate by encoding everything in its UserData argument.

Convenient sending can be achieved by installing non-virtual methods in the TReport class, which encode the arguments in UserData and send them via ReportBase::report().

Convenient receiving can be achieved by installing virtual methods in the TReport class, which can be simply overloaded by the receiver. Downside of this is that adding virtual methods breaks binary compatibility.