Binder documentation - RFC/peer review

[devi prasad]

Hi, I'm preparing a document describing Binder implementation in
Android. I've already written about four pages combining
"how-to-write-a-binder-program" with "how-does-it-work" style of
writing. As I progressed, I thought it might be useful to listen to
what others think about such an approach. So I'm attaching the
document for your comments. Please take a look at it and provide your
suggestions, opinions, views, and what not, to make this a useful
document.
FYI, English is not my mother tongue. Therefore, my style may not be
smooth on ears that converse in English :-) Please feel free to
suggest improvements not only on the content but also on the overall
style and readability.

Thank you for your time and patience
Devi Prasad

PS: I've posted this on both platform and framework groups. I'm always
confused about these two forums ;-)

[devi prasad]

I received a couple emails pointing out that the document in incomplete.
Please note that this document is unfinished and therefore incomplete,
as it stands now. I'm presenting this (draft, incomplete document) to
the group just to hear the views of others who may convince me to
change the presentation style.

thanks
Devi Prasad

[Dianne Hackborn]

Hi, nice job!  One small comment -- the dump() method actually for debugging.  An object can implement by printing interesting parts of its current state as text to the output stream.  In particular, this is what makes the dumpsys command work -- all dumpsys really does is call dump() on whatever IBinder objects it wants to print.

--
Dianne Hackborn
Android framework engineer
hac...@android.com

Note: please don't send private questions to me, as I don't have time to provide private support, and so won't reply to such e-mails.  All such questions should be posted on public forums, where I and others can see and answer them.

[devi prasad]

Hi, Dianne - thanks for the encouraging words!

I've seen dump() getting used for the debugging purpose you mentioned.
I'll certainly mention it in the upcoming draft.
That said, I also see a use that I have mentioned; after all, it is
declared pure virtual and so we may as well want our components to
serialize themselves to a stream when required. This will fit into the
scheme I was mentioning in the document - services that pool objects
if they are not pinged for a period of time.

thanks anyway. I'll keep working in my spare time!

[devi prasad]

Hi, I have a new section in the Binder documentation that I started a
couple weeks ago. I would like to share this specific section here.
FYI, I thought it would be a good idea to introduce the reader to
important ideas with the help of simple programs that use binder api.
So this writeup is intended to provide an intro to client-side binder
usage.

Let me know everything about this writing!

thanks for your time
Devi Prasad

On Mon, Jul 20, 2009 at 8:35 PM, devi prasad<dpra...@gmail.com> wrote:
> Hi, Naveen - thanks for your interest. I'll definitely address your
> questions too! I want to complete this soon. But my day job doesn't
> let me do binder documentation :) I need to squeeze this in the time I
> find, which I definitely will!
>
> On Mon, Jul 20, 2009 at 7:42 PM, Naveen K<nave...@gmail.com> wrote:
>>
>> Hi Devi,
>>
>> Can you also throw some light on how the IBinder interface is
>> connected to the
>> aidl files? When you define an abstract method in an aidl file, you
>> can specify
>> if the parameter is an input parameter or an output parameter. I was
>> looking
>> around for examples which contain an out parameter just to understand
>> where
>> the memory is allocated for this parameter. But I haven't found any.
>> It will great
>> if you can extend your document to cover that region too.
>>
>> Thank you,
>> Naveen

>>> > hack...@android.com

[dan raaka]

you can use docs.google.com or some wiki to let contribute .. if you intend solicit external contributors ..

-Dan

[devi prasad]

I agree moving this to Google docs would be a good idea. Are you aware
of any baseline where I can move my initial drafts? or Should I create
one? Any pointers would help...

thanks
Devi Prasad