Page MenuHomePhabricator

eina: eina_future_as_value needs improved docs
Open, TrivialPublic

Description

The docs for eina_future_as_value need to explain why the returned Eina_Value is of type Eina_promise instead of Eina_Future as the method name seems to suggest.

The discussion started in D8334#151205.

There is a method called eina_promise_as_value() which takes an Eina_Promise and wraps it in an Eina_Value.
And then there is eina_future_as_value() which indeed takes an Eina_Future and produces an Eina_Value. but the value does not wrap an Eina_Future but an Eina_Promise which gets fulfilled at the same time the original future does.
Therefore, eina_future_as_value() seems a bit misleading.

segfaultxavi triaged this task as Trivial priority.

I would think that the main misleading things is that the returned Eina_Value is of type EINA_VALUE_TYPE_PROMISE and that there is no EINA_VALUE_TYPE_PROMISE. That might require more documentation. Otherwise I feel the name does match what the function does, it takes an Eina_Future and return an Eina_Value.

Main reasoning is that someone that is looking on how to return an Eina_Value from an Eina_Future would find this function very quickly and wouldn't have to understand much of what it does to use it.

segfaultxavi renamed this task from eina: eina_future_as_value might be misleading to eina: eina_future_as_value needs improved docs.Mar 20 2019, 4:03 AM
segfaultxavi claimed this task.
segfaultxavi updated the task description. (Show Details)
segfaultxavi edited projects, added efl: docs; removed efl.

@cedric Should I add EINA_VALUE_TYPE_PROMISE to the list of public Eina_Value types in eina_value.h?
Why is it private?

cedric added a comment.Sep 6 2019, 5:08 AM

I don't think it make sense as you really only want to pass value and promise do not have value only future will have. When a user get an eina value, it is usually to read a value. A promise is the writing end of a value, so a user won't be able to read a value and it might be very weird to use that way. The current API really make the eina value only the reading end aka a future from a promise, the rest is internal cooking.

I can explain why eina_future_as_value actually returns a Promise, and I can explain what the user has to do to retrieve the original value from it.
BUT STILL, eina_future_as_value (and eina_promise_as_value too) returns an Eina_Value of unknown type to the user.
What's the users supposed to do with that Eina_Value?

cedric added a comment.Sep 6 2019, 7:20 PM

Oh,I see. I need to look more at the code from a computer. Ping me next week on this.

Next week has arrived (and it's almost gone): Ping!