CCSM API

CCSM maintains sets, so the CCSM API simply provides a basic set management interface. The meaning of the set depends on how it is used, what it is used to represent. Since the use of the set determines what its elements are, and the rules governing set membership modification the most crucial aspect of the CCSM API with respect to semantics are the set attributes describing conditions under which elements should be added to ordeleted from the set, and the conditions under which callback routines in the code using a set should be invoked. While the CCSM API is in many ways simple and striaghtforward, it can be used in a number of subtle ways.

Set Attribute Flags

These describe attributes of the set that affect what it describes and how membership in the set should change as various events occur in the system. One of the most important CCSM set attributes is that designating a set as a singleton, which limits the set to a single member. This is most commonly used to associate the set name with specific computation components such as threads. The current set of attributes is primarily motivated by CCSM use for discovering computation structure.

CCSM_SINGLETON_SET

This restricts the set to having a single member. This is useful for associating set names with threads for Group Scheduling and Datastream specification purposes, which are independent of invocation context attributes such as PID. Similarly, associating names which are invariant across invocations may also be useful for other computation components.

CCSM_ADD_CHILD_ON_FORK

If the parent is a member of this set, add children to this set.

CCSM_ADD_ON_SIGNAL_SEND

If either the sender or receiver of a signal is a member of this set, then add the other side the signal exchange to this set.

CCSM_ADD_ON_SOCKET_SR

There are two possible conditions, either the sender/receiver is a member of a set or the socket is a member of a set. If the socket, a passive component, is a member of a set with this flag asserted, then we make the sender to / receiver from the socket a member of this set. If the sender to / receiver from the socket is a member of a set with this flag asserted, then we make the socket a member of this set.

Note that UDP sockets are connectionless, so we phrase this in terms of the sender and receiver of a message so that it can be common to all socket types.

CCSM_ADD_ON_PIPE_RW

There are two possible conditions, either the reader of / writer to the pipe is a member of a set or the pipe is a member of a set. If the pipe, a passive component, is a member of a set with this flag asserted, then we make the reader of / writer to the pipe a member of this set. If the reader of / writer to the pipe is a member of a set with this flag asserted, then we make the pipe a member of this set. We assume at the moment that this is for both named and unnamed pipes.

CCSM_ADD_FLOCK_USERS

If the file lock, a passive component, is a member of a set with this flag asserted, then add the user of the file lock to this set.

CCSM_ADD_SHMSEG_USERS

If the shared memory segment, a passive component, is a member of a set with this flag asserted, add users of the shared memory segment to this set. Note, however, that do to the inherent semantics of shared memory segments only attach/detach/destroy operations can be observed at the kernel level under normal operating conditions because read and write to mapped shared memory segments are supported at the hardware level and do not require system calls.

• The only way to observe such read and write operations would be to manipulate the memory map for the segment in every user’s address space and create code at the trap handler level that would note the use of the shared memory segment and manipulate maps in such a way as to permit the operation and restore the detection setup. Obviously this would impose large overhead and be quite complex.

CCSM_ADD_USING_SOFTIRQ

If the Soft IRQ, an active component, is a member of a set with this flag asserted, then add the user of this Soft IRQ to this set.

CCSM_ADD_USING_HARDIRQ

If the Hard IRQ, an active component, is a member of a set with this flag asserted, then add the user of this Hard IRQ to this set.

CCSM_REMOVE_SET_ON_EMPTY

This will cause CCSM to clean up a set when all members of that set have been removed.

Callback Condition Flags

These flags are used both registering a callback routine and as an argument when the callback routine is called. At registration time they specify the conditions under which the code registering the call-back wished the callback to be invoked. When the callback is invoked, the condition under which it was invoked by the flag argument setting.

Every callback routine has the following generic interface:

void <callback_name>(unsigned int condition, struct ccsm_set *set, void *args, size_t size);

The condition argument will have one of the following flag values set to indicate the condition causing the invocation of the callback. The set parameter is the handle to the set causing the invocation. The args parameter is a pointer to a callback specific structure specified at registration time which contains any additional callback specific information required for proper callback execution. The size parameter gives the size of the args structure.

CCSM_CONDITION_NAME_BINDING

Binding of a named singleton set to a specific handle. Note that this would be used by Group Scheduling in support of Rendezvous when an element has been added to a Group by name, but no singleton set with that name exists. In that case Group Scheduling creates the singleton set with the desired name and registers a callback with this condition flag asserted.

CCSM_CONDITION_MEMBER_ADDITION

Addition of a member to a set.

CCSM_CONDITION_MEMBER_SUBTRACTION

Subtraction/removal of a member from a set.

CCSM_CONDITION_SET_MEMBERSHIP_CHANGE

Modification of set membership. i.e. either member addition or subtraction. Note, this is likely to be used far more frequently or perhaps exclusively in preference addition or subtraction separately.

CCSM_CONDITION_SET_DELETION

The set the callback has registered with is being deleted. This callback condition is always set for all callbacks by definition.

FIXME.IDEAS: at the set level, consider the following redundant information representations:

• “no callbacks / callbacks exist” flag: callback list_empty of callback listhead tells us if any callbacks are listed or not but an explicit flag might make any code that cares cleaner
• per-set aggregate flag of callback actions currently registered with the set. This would represent at the set level the union of all conditions under which any of its callbacks have registered. Again, redundant but, perhaps, convenient.

CCSM Member Types

This is the set of computation component types understood by the current CCSM framework. Note that the use of all but the CCSM_TYPE_SET is limited to singleton sets.

CCSM_TYPE_SET

This indicates that the member is a general set and not a singleton

CCSM_TYPE_TASK

This indicates that the member is a singleton representing an active component of type task

CCSM_TYPE_FLOCK

This indicates that the member is a singleton representing a passive component of type file lock

CCSM_TYPE_SOCKET

This indicates that the member is a singleton representing a passive component of type socket

CCSM_TYPE_PIPE

This indicates that the member is a singleton representing a passive component of type pipe

CCSM_TYPE_NAMED_PIPE

This indicates that the member is a singleton representing a passive component of type named pipe

CCSM_TYPE_SHMSEG

This indicates that the member is a singleton representing a passive component of type shared memory segment

CCSM_TYPE_KERNEL_MUTEX

This indicates that the member is a singleton representing a passive component of type kernel mutex

CCSM Error Codes

This is the set of unique CCSM error return values. Note that individual API calls may return a subset of these.

CCSM_ERROR_SEVERE

Currently a catch-all error for fatal CCSM system problems.

CCSM_ERROR_NO_SUCH_SET

Indicates that a referenced set does not exist

CCSM_ERROR_NO_SUCH_SINGLETON

Indicates that a referenced set which should be a singleton under the semantics of the API does not exist

CCSM_ERROR_IS_NOT_SINGLETON

Indicates that a referenced set which should be a singleton under the semantics of the API is not a singleton

CCSM_ERROR_SET_ALREADY_EXISTS

Indicates that a referenced set already exists when the semantics of the API assumed that the referenced set did not currently exist

API Calls

These are the basic CCSM operations available to client code.

struct ccsm_set *ccsm_create_set(char *name, int *created)

Create a set with the given name and asserted attribute flags. Note that the attribute flags described here are used to associate various properties with other set operations on a given set. For example, CCSM_ADD_CHILD_ON_FORK denotes the set property that any member of the set forking a child task should cause the child task to be added to the set. If the set did not already exist, a handle is returned to the new set and the created flag is set to true. If the set already existed, the handle to the set is still returned, but the created flag is set to false. [edit] ccsm_add_member_by_handle

int ccsm_add_member_by_handle(char *set_name, void *generic_handle)

Add to the set with the given name a new member with the given generic handle. The generic handle can be either a reference to a computation component or to a ccsm_set. This routine consults the by-handle hash table and discovers as a result whether the generic handle is a component or a ccsm_set reference. Three possibilities exist: (1) no set associated with this generic_handle exists or (2) a set with this handle exists, singleton or not.

Under condition (1), an error should be returned indicating that a singleton set representing the computation component should be created, as a name for the singleton set representing the computation component should be specified. Under condition (2) the set referenced by the generic handle is aded to the set specified by name.

int ccsm_is_member_by_name(char *set_name, char *member_name)

Check if a member with the given name is a member of the set with the given name. [edit] ccsm_is_member_by_handle

int ccsm_is_member_by_handle(char *set_name, void *generic_handle)

The generic handle input parameter may refer to either a computation component or a ccsm_set. This routine consults the by-handle hash table and discovers as a result whether the generic handle is a component or a ccsm_set reference. If it is a component handle, then its representation by a singleton set is discovered and the handle to the singleton set is used to consult the by-handle hash table in order to find the computation component set membership. If the generic handle was a set handle to begin with, the set membership is discovered in the first consultation of the by-handle hash table.

FIXME.J - consider changing the current implementation of destroy_by_name to be by_handle

int ccsm_destroy_set_name(char *name)

Attempt to explicitly destroy a set with the given name. The set will not be destroyed if the set has any members or callbacks present.

int ccsm_destroy_set_by_handle(void *set_handle)

Attempt to explicitly destroy the set with the given handle. If you have the name of a set, you must find the handle first. [edit] ccsm_create_singleton

int ccsm_create_singleton(char *set_name, unsigned int component_type, void *component_handle)

Create a singleton set with the given name of the given type representing the computation component referenced by the given handle.

ccsm_set *ccsm_find_set_by_name(char *name)

Return a handle to the given set with the given name.

struct ccsm_set *ccsm_find_singleton_by_handle(void *component_handle)

Return a handle to the singleton set representing the component with component_handle.

struct ccsm_set_iter *ccsm_find_memberships(void *generic_handle)

The generic handle may refer to either a computation component or a set. If the generic handle refers to an existing set, the routine uses the by_handle hash table to find the list of sets in which the referenced set is a member. If the generic handle refers to a computation component the routine consults the by_handle hash table to find the singleton set representing this component. If no such singleton exists, then set membership is empty, and an empty iterator is returned. If the singleton set exists, the by_handle hash table is consulted a second time to discover it list of set memberships. Under all conditions, the routine now knows if the set membership is empty or not and returns an empty iterator if appropriate. If a non-empty set of memberships exists the routine constructs a list representing the set of memberships. It increments the reference count of all sets on the list and associates the list with the iterator.

struct ccsm_set *ccsm_handle_iterator_next(struct ccsm_set_iter *iter)

Returns a handle to the next set in the iterators list of set memberships.

void ccsm_handle_iterator_reset()

Resets the iterator back to the beginning of the list.

void ccsm_handle_iterator_free()

This routines frees the iterator structure, the associated structures representing the set of list memberships, and decrements the reference count of all the sets on the list.

static void ccsm_remove_task(struct task_struct *task) Attempts to remove a task referenced by the given task_struct pointer. This is currently most useful for an internal call from exit.c that attempts to remove member structures referencing a task that no longer exists.

Operations Supported

• creation of non-singleton sets
• creation of singleton sets
• addition of members to non-singleton sets
• removal of members from non-singleton sets
  • currently set is automatically removed when no remaining members exist
    • should be supplanted by flag, not hard-coded
• destruction of set by name
• destruction of singleton sets by computation component pointer
• is_member_by_name
• is_member_by_handle