diff options
author | iphydf <iphydf@users.noreply.github.com> | 2016-08-10 13:46:04 +0100 |
---|---|---|
committer | iphydf <iphydf@users.noreply.github.com> | 2016-08-17 14:57:20 +0100 |
commit | dd8a568141b43546521ca438d861e00c26051f6c (patch) | |
tree | 98f3f9a871f164b20693eca89eb0c8bf2ae826ed /other/apidsl/tox.in.h | |
parent | cebf64a588039c202880659a85d070126bcc68da (diff) |
Make self_connection_status callback stateless.
**What are we doing?**
We are moving towards stateless callbacks. This means that when registering a
callback, you no longer pass a user data pointer. Instead, you pass a user data
pointer to tox_iterate. This pointer is threaded through the code, passed to
each callback. The callback can modify the data pointed at. An extra indirection
will be needed if the pointer itself can change.
**Why?**
Currently, callbacks are registered with a user data pointer. This means the
library has N pointers for N different callbacks. These pointers need to be
managed by the client code. Managing the lifetime of the pointee can be
difficult. In C++, it takes special effort to ensure that the lifetime of user
data extends at least beyond the lifetime of the Tox instance. For other
languages, the situation is much worse. Java and other garbage collected
languages may move objects in memory, so the pointers are not stable. Tox4j goes
through a lot of effort to make the Java/Scala user experience a pleasant one by
keeping a global array of Tox+userdata on the C++ side, and communicating via
protobufs. A Haskell FFI would have to do similarly complex tricks.
Stateless callbacks ensure that a user data pointer only needs to live during a
single function call. This means that the user code (or language runtime) can
move the data around at will, as long as it sets the new location in the
callback.
**How?**
We are doing this change one callback at a time. After each callback, we ensure
that everything still works as expected. This means the toxcore change will
require 15 Pull Requests.
Diffstat (limited to 'other/apidsl/tox.in.h')
-rw-r--r-- | other/apidsl/tox.in.h | 19 |
1 files changed, 15 insertions, 4 deletions
diff --git a/other/apidsl/tox.in.h b/other/apidsl/tox.in.h index 577515b1..6e65ed1f 100644 --- a/other/apidsl/tox.in.h +++ b/other/apidsl/tox.in.h | |||
@@ -86,6 +86,19 @@ extern "C" { | |||
86 | * callback will result in no callback being registered for that event. Only | 86 | * callback will result in no callback being registered for that event. Only |
87 | * one callback per event can be registered, so if a client needs multiple | 87 | * one callback per event can be registered, so if a client needs multiple |
88 | * event listeners, it needs to implement the dispatch functionality itself. | 88 | * event listeners, it needs to implement the dispatch functionality itself. |
89 | * | ||
90 | * The last argument to a callback is the user data pointer. It is passed from | ||
91 | * ${tox.iterate} to each callback in sequence. | ||
92 | * | ||
93 | * The user data pointer is never stored or dereferenced by any library code, so | ||
94 | * can be any pointer, including NULL. Callbacks must all operate on the same | ||
95 | * object type. In the apidsl code (tox.in.h), this is denoted with `any`. The | ||
96 | * `any` in ${tox.iterate} must be the same `any` as in all callbacks. In C, | ||
97 | * lacking parametric polymorphism, this is a pointer to void. | ||
98 | * | ||
99 | * Old style callbacks that are registered together with a user data pointer | ||
100 | * receive that pointer as argument when they are called. They can each have | ||
101 | * their own user data pointer of their own type. | ||
89 | */ | 102 | */ |
90 | 103 | ||
91 | /** \subsection threading Threading implications | 104 | /** \subsection threading Threading implications |
@@ -713,7 +726,7 @@ inline namespace self { | |||
713 | * | 726 | * |
714 | * TODO: how long should a client wait before bootstrapping again? | 727 | * TODO: how long should a client wait before bootstrapping again? |
715 | */ | 728 | */ |
716 | event connection_status { | 729 | event connection_status const { |
717 | /** | 730 | /** |
718 | * @param connection_status Whether we are connected to the DHT. | 731 | * @param connection_status Whether we are connected to the DHT. |
719 | */ | 732 | */ |
@@ -734,7 +747,7 @@ const uint32_t iteration_interval(); | |||
734 | * The main loop that needs to be run in intervals of $iteration_interval() | 747 | * The main loop that needs to be run in intervals of $iteration_interval() |
735 | * milliseconds. | 748 | * milliseconds. |
736 | */ | 749 | */ |
737 | void iterate(); | 750 | void iterate(any user_data); |
738 | 751 | ||
739 | 752 | ||
740 | /******************************************************************************* | 753 | /******************************************************************************* |
@@ -858,7 +871,6 @@ inline namespace self { | |||
858 | * If this parameter is NULL, the function has no effect. | 871 | * If this parameter is NULL, the function has no effect. |
859 | */ | 872 | */ |
860 | get(); | 873 | get(); |
861 | |||
862 | } | 874 | } |
863 | 875 | ||
864 | 876 | ||
@@ -1058,7 +1070,6 @@ namespace friend { | |||
1058 | */ | 1070 | */ |
1059 | const bool exists(uint32_t friend_number); | 1071 | const bool exists(uint32_t friend_number); |
1060 | 1072 | ||
1061 | |||
1062 | } | 1073 | } |
1063 | 1074 | ||
1064 | inline namespace self { | 1075 | inline namespace self { |