shady.common.multi
Interface MultiShadyCommonAPI

All Known Subinterfaces:

MultiShadySimAPI

All Known Implementing Classes:

MultiShadyCommon, MultiShadySim

public interface MultiShadyCommonAPI

MultiShady API subset that is shared between the simulator and the hardware.

A MultiShady is a set of one or more MemberShadys (see MemberShadyCommonAPI). The number of MemberShadys (numMembers()) can be changed at runtime (addMember(shady.common.multi.MemberShadyCommonAPI), removeLastMember(), clearMembers()).

This API is not designed for MT use: it is expected that only a single thread makes calls to any of the MemberShady's APIs, or that external synchronization is performed. A synchronization convention is that any thread wishing to perform an atomic bulk operation on one or more members should synchronize on the MultiShady object.

Copyright (C) 2006 Marsette A. Vona, III

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Author:

Marsette (Marty) A. Vona, III

Nested Class Summary

static interface

MultiShadyCommonAPI.MemberProcessor A processor for members.

Field Summary

static java.lang.String

cvsid CVS id.

Method Summary

int	addMember(MemberShadyCommonAPI newMember) Add a member at the end of the list.
int	addMember(ShadyPose pose) Make and add a new member at the end of the list.
void	clearMembers() Remove all members.
void	exec(java.util.Collection operations) Atomically execute the specified BoundOperations, in order.
void	forEachMember(MultiShadyCommonAPI.MemberProcessor processor) Atomically process all members.
void	forMembers(java.util.Collection keys, MultiShadyCommonAPI.MemberProcessor processor) Atomically process a subset of the members.
vona.time.Clock	getClock() Get the clock this MultiShady is using.
MemberShadyCommonAPI	getMember(int index) Get a member by index.
MemberShadyCommonAPI	getMember(java.lang.Integer index) Get a member by index.
MemberShadyCommonAPI	getMember(java.lang.String name) Get a member by name.
java.util.Set	getMembers() Get an unmodifiable view of the set of MemberShadys in this MultiShady.
int	getNumActiveActuators() Get sum of ShadyCommonAPI.getNumActiveActuators() over all members.
MemberShadyCommonAPI	makeMember(ShadyPose pose) Make and a new member but don't add it.
int	numMembers() Get the number of MemberShadys in this MultiShady.
MemberShadyCommonAPI	removeLastMember() Remove the last member.
void	reset() ShadyCommonAPI.reset() all members.
void	stop(boolean estop) ShadyCommonAPI.stop(boolean) all members.

Field Detail

cvsid

static final java.lang.String cvsid

CVS id.

See Also:

Constant Field Values

Method Detail

numMembers

int numMembers()

Get the number of MemberShadys in this MultiShady.

Returns:

the number of MemberShadys in this MultiShady

getMembers

java.util.Set getMembers()

Get an unmodifiable view of the set of MemberShadys in this MultiShady.

Returns:

an unmodifiable view of the (synchronized) set of MemberShadys in this MultiShady (will track the set of members as it evolves)

getMember

MemberShadyCommonAPI getMember(int index)

Get a member by index.

Parameters:

index - the index of the member to get, zero-based

getMember

MemberShadyCommonAPI getMember(java.lang.Integer index)

Get a member by index.

Parameters:

index - the index of the member to get, zero-based

getMember

MemberShadyCommonAPI getMember(java.lang.String name)

Get a member by name.

Parameters:

name - the name of the member to get

addMember

int addMember(MemberShadyCommonAPI newMember)

Add a member at the end of the list.

newMember has its index and MultiShady reference set, and has its name set iff it was not previously set.

Parameters:

newMember - the new member to add

Returns:

the new number of members

addMember

int addMember(ShadyPose pose)

Make and add a new member at the end of the list.

Calls makeMember(shady.common.ShadyPose) and then addMember(MemberShadyCommonAPI).

Parameters:

pose - the pose of the new member

Returns:

the new number of members

makeMember

MemberShadyCommonAPI makeMember(ShadyPose pose)

Make and a new member but don't add it.

Parameters:

pose - the pose of the new member

Returns:

the new number of members

removeLastMember

MemberShadyCommonAPI removeLastMember()

Remove the last member.

By the convention defined in the class header doc, implementations should be synchronized.

The removed member has its index set to -1 and its MultiShady reference nulled, but does not have its name changed.

Returns:

the removed member, or null if none

clearMembers

void clearMembers()

Remove all members.

By the convention defined in the class header doc, implementations should be synchronized.

forEachMember

void forEachMember(MultiShadyCommonAPI.MemberProcessor processor)

Atomically process all members.

By the convention defined in the class header doc, implementations should be synchronized.

The extra parameter of MultiShadyCommonAPI.MemberProcessor.process(shady.common.multi.MemberShadyCommonAPI, java.lang.Object) will be set null by default.

Parameters:

processor - the non-null processor to call for each member

forMembers

void forMembers(java.util.Collection keys,
                MultiShadyCommonAPI.MemberProcessor processor)

Atomically process a subset of the members.

By the convention defined in the class header doc, implementations should be synchronized.

The extra parameter of MultiShadyCommonAPI.MemberProcessor.process(shady.common.multi.MemberShadyCommonAPI, java.lang.Object) will be set to the corresponding key.

Parameters:

keys - a non-null collection of MemberShadyCommonAPI, String, or Integer identifying members directly, by name, or by index, respectively. If multiple keys resolve to the same member the member will be processed multiple times.

processor - the non-null processor to call for each member corresponding to each key

exec

void exec(java.util.Collection operations)

Atomically execute the specified BoundOperations, in order.

By the convention defined in the class header doc, implementations should be synchronized.

Parameters:

operations - the BoundOperations to execute, in iterator order, not null

stop

void stop(boolean estop)

ShadyCommonAPI.stop(boolean) all members.

By the convention defined in the class header doc, implementations should be synchronized.

reset

void reset()

ShadyCommonAPI.reset() all members.

By the convention defined in the class header doc, implementations should be synchronized.

getNumActiveActuators

int getNumActiveActuators()

Get sum of ShadyCommonAPI.getNumActiveActuators() over all members.

By the convention defined in the class header doc, implementations should be synchronized.

Returns:

sum of MemberShadyCommonAPI.getNumActiveActuators() over all members

getClock

vona.time.Clock getClock()

Get the clock this MultiShady is using.

Returns:

the clock this MultiShady is using