ChannelGroup Javadoc updated - please review

[Trustin Lee]

Hi Frederic,

On Thu, Apr 23, 2009 at 7:12 PM, Frederic Bregier <fredbregier at free.fr> wrote:
> 1) In ChannelGroup, the example show how to add the "child" channels
> but did not show the add of the "parent" channel.
> As in your comment, you specifiy the way parent and child are taken
> into account when the close on the ChannelGroup occurs, perhaps you
> could set something like (if it was missed and not in intentional):
>
> public static void main(String[] args) throws Exception {
>     ServerBootstrap b = new ServerBootstrap(..);
>     ...
>
>     // Start the server
>     b.getPipeline().addLast("handler", new MyHandler());
>     Channel serverChannel = b.bind(..);
>     // Add the Server Channel to the ChannelGroup
>     allchannels.add(serverChannel);
>
>     ... Wait until the shutdown signal reception ...
>
>     // Close the serverChannel and then all accepted connections.
>     allChannels.close().awaitUninterruptibly();
>     b.releaseExternalResources();
>  }

Nice catch!  Fixed.

> 2) Still in ChannelGroup, maybe a simple example on how to use bulk
> operations other than close (a lot of question in the ML about that)
> like "How to write to all registered and active channels in a group"?
>
> Simply something like allChannels.write(messageBroadcast)

Added an example section as advised.

> 3) In ChannelGroupFuture, you specified that await should be banned
> as most as possible. But in the example of ChannelGroup, you used
> await (even awaitUninterruptibly). I know that this is perfectly ok
> here since it is outside all IO threads. However, perhaps in the doc
> you could say that there might be an exception when close is called
> if the close is called outside any IO threads or at least make a
> remark in the ChannelGroup?
> Another way could be to create a listener that runs
> releaseExternalResources?
> I don't know which is better...

I added another paragraph to tell the reader that calling await*() is
fine if it's called from a non-I/O thread.  Check ChannelGroupFuture
and ChannelFuture.

> 4) A question (might be a comment on the doc?), what is the purpose
> of the find method in the ChannelGroupFuture. I have some difficulty
> to see what kind exactly of ChannelFuture it returns?

You might want to know the outcome of an individual channel operation
because a group I/O operation is composed of more than one operation
that affects the channels in the group.  For example, if you
broadcasted a message to 1000 channels, 1000 ChannelFutures are
created, and you can find a specific ChannelFuture with
ChannelGroupFuture.find(..).

> Other than that, as always, perfect! What I like in Netty is that the
> documentation is growing fast and is useful!!! Thanks to you!!!

Thanks for your quick feed back!

Cheers,

— Trustin Lee, http://gleamynode.net/