Add API to get next fresh message

[link2xt]

Rust: Context.get_next_fresh_msg()
C: dc_get_next_fresh_msg()
JSON-RPC: get_next_fresh_msg method

[r10s]

what if there is no next fresh message?

[r10s]

waits until there is one.

is this also true for cffi/jsonprc? if so, this information should be added to the docs there as well.

maybe also add a line for the usecase. though i am sure, there is concrete need somewhere, the uscase is not clear to at least to me :)

[r10s]

or maybe better rename the function to wait_for_next_fresh_message(), i would not expect a get-function to block for maybe hours.

[link2xt]

I named it similarly to get_next_event() for consistency. We can call it something with wait, but then there can be an impression that get_next_event() is somehow different and non-blocking.

[r10s]

hm, get_next_event() is called on an explicit event emitter object that does not have many other usages, so that seems less confusing than for the context where all the other get() work differently.

but i agree, wait() would have been better for the context emitter as well.

i still suggest to not repeat the "mistake" use sth. with "wait" in the name here. maybe we can rename the other usages accordingly when we iterate over or so.

[link2xt]

@r10s The use case is to make it easier to write bots that have only a single thread and loop for the next message to process in infinite loop, then process them, then mark as read, like this:

if not configured:
    configure
start
loop:
    msg = get_next_fresh_msg()
    process msg, maybe break the loop
    mark msg as read

Then you can be sure all messages are processed in the order they arrive, bot processes old messages after starting and never forgets about incoming message because it was busy processing another message already.

It makes easier to quick start with bots without using any frameworks. There is a PR with a quickstart deltachat-bot/bot-pages#45 but example code is currently busy looping on get_fresh_messages().

Users can then switch to advanced techniques like writing an event loop that, processing events and so on, but then there is a need to think about how message processing (initial processing of old messages and new messages that arrive while the bot works) works together with event processing, use some synchronization primitives available in the language bot is written in etc. With this simple API synchronization is done in the core.

[r10s]

lgtm, i'd modify the name and maybe add a line "this is mainly useful for bot usage" or so to the comment.

but these are no blockers.

[link2xt]

I still don't like that there is no way to stop this loop. With events loop you call stop_io, receive an INFO event and then break out of the loop, but this function will not return at all.

Maybe it really makes more sense to have a function that only waits and may be interrupted, but you have to check if there are actually any messages yourself.

[link2xt]

I found a better way to do a simple bot without IPC and all this stuff. An echo bot in #3734 is running an event loop in the main task and has a separate function that processes all fresh messages. Will try to get it into quickstart guide then.