# Callbacks Classes

This section defines the classes used for callback registration, management, and user-defined callbacks.

Contents

Callbacks Classes | This section defines the classes used for callback registration, management, and user-defined callbacks.
uvm_callbacks #(T,CB) | The uvm_callbacks class provides a base class for implementing callbacks, which are typically used to modify or augment component behavior without changing the component class.
uvm_callback_iter | The uvm_callback_iter class is an iterator class for iterating over callback queues of a specific callback type.
uvm_callback | The uvm_callback class is the base class for user-defined callback classes.

## uvm_callbacks #(T,CB)

The uvm_callbacks class provides a base class for implementing callbacks, which are typically used to modify or augment component behavior without changing the component class. To work effectively, the developer of the component class defines a set of “hook” methods that enable users to customize certain behaviors of the component in a manner that is controlled by the component developer. The integrity of the component’s overall behavior is intact, while still allowing certain customizable actions by the user.

To enable compile-time type-safety, the class is parameterized on both the user-defined callback interface implementation as well as the object type associated with the callback. The object type-callback type pair are associated together using the `uvm_register_cb macro to define a valid pairing; valid pairings are checked when a user attempts to add a callback to an object.

To provide the most flexibility for end-user customization and reuse, it is recommended that the component developer also define a corresponding set of virtual method hooks in the component itself. This affords users the ability to customize via inheritance/factory overrides as well as callback object registration. The implementation of each virtual method would provide the default traversal algorithm for the particular callback being called. Being virtual, users can define subtypes that override the default algorithm, perform tasks before and/or after calling super.<method> to execute any registered callbacks, or to not call the base implementation, effectively disabling that particular hook. A demonstration of this methodology is provided in an example included in the kit.

Summary

uvm_callbacks #(T,CB)
The uvm_callbacks class provides a base class for implementing callbacks, which are typically used to modify or augment component behavior without changing the component class.
Class Hierarchy
uvm_typed_callbacks#(T)
uvm_callbacks#(T,CB)
Class Declaration
> class uvm_callbacks #(
> | type | T | = | uvm_object,
> | type | CB | = | uvm_callback
> ) extends uvm_typed_callbacks#(T)
T | This type parameter specifies the base object type with which the CB callback objects will be registered.
CB | This type parameter specifies the base callback type that will be managed by this callback class.
Add/ delete interface |
add | Registers the given callback object, cb, with the given obj handle.
add_by_name | Registers the given callback object, cb, with one or more uvm_components.
delete | Deletes the given callback object, cb, from the queue associated with the given obj handle.
delete_by_name | Removes the given callback object, cb, associated with one or more uvm_component callback queues.
Iterator Interface | This set of functions provide an iterator interface for callback queues.
get_first | Returns the first enabled callback of type CB which resides in the queue for obj.
get_last | Returns the last enabled callback of type CB which resides in the queue for obj.
get_next | Returns the next enabled callback of type CB which resides in the queue for obj, using itr as the starting point.
get_prev | Returns the previous enabled callback of type CB which resides in the queue for obj, using itr as the starting point.
Debug |
display | This function displays callback information for obj.

### T

This type parameter specifies the base object type with which the CB callback objects will be registered. This object must be a derivative of uvm_object.

### CB

This type parameter specifies the base callback type that will be managed by this callback class. The callback type is typically a interface class, which defines one or more virtual method prototypes that users can override in subtypes. This type must be a derivative of uvm_callback.

### Add/ delete interface

### add

> static function void add(
> | T | obj, |  |
> | uvm_callback | cb, |  |
> | uvm_apprepend | ordering | = | UVM_APPEND
> )

Registers the given callback object, cb, with the given obj handle. The obj handle can be null, which allows registration of callbacks without an object context. If ordering is UVM_APPEND (default), the callback will be executed after previously added callbacks, else the callback will be executed ahead of previously added callbacks. The cb is the callback handle; it must be non-null, and if the callback has already been added to the object instance then a warning is issued. Note that the CB parameter is optional. For example, the following are equivalent:

>     uvm_callbacks#(my_comp)::add(comp_a, cb);
>     uvm_callbacks#(my_comp, my_callback)::add(comp_a,cb);

### add_by_name

> static function void add_by_name(
> | string | name, |  |
> | uvm_callback | cb, |  |
> | uvm_component | root, |  |
> | uvm_apprepend | ordering | = | UVM_APPEND
> )

Registers the given callback object, cb, with one or more uvm_components. The components must already exist and must be type T or a derivative. As with add the CB parameter is optional. root specifies the location in the component hierarchy to start the search for name. See uvm_root::find_all for more details on searching by name.

### delete

> static function void delete(
> | T | obj,
> | uvm_callback | cb
> )

Deletes the given callback object, cb, from the queue associated with the given obj handle. The obj handle can be null, which allows de-registration of callbacks without an object context. The cb is the callback handle; it must be non-null, and if the callback has already been removed from the object instance then a warning is issued. Note that the CB parameter is optional. For example, the following are equivalent:

>     uvm_callbacks#(my_comp)::delete(comp_a, cb);
>     uvm_callbacks#(my_comp, my_callback)::delete(comp_a,cb);

### delete_by_name

> static function void delete_by_name(
> | string | name,
> | uvm_callback | cb,
> | uvm_component | root
> )

Removes the given callback object, cb, associated with one or more uvm_component callback queues. As with delete the CB parameter is optional. root specifies the location in the component hierarchy to start the search for name. See uvm_root::find_all for more details on searching by name.

### Iterator Interface

This set of functions provide an iterator interface for callback queues. A facade class, uvm_callback_iter is also available, and is the generally preferred way to iterate over callback queues.

### get_first

> static function CB get_first (
> | ref | int | itr,
> | input | T | obj
> )

Returns the first enabled callback of type CB which resides in the queue for obj. If obj is null then the typewide queue for T is searched. itr is the iterator; it will be updated with a value that can be supplied to get_next to get the next callback object.

If the queue is empty then null is returned.

The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator interface.

### get_last

> static function CB get_last (
> | ref | int | itr,
> | input | T | obj
> )

Returns the last enabled callback of type CB which resides in the queue for obj. If obj is null then the typewide queue for T is searched. itr is the iterator; it will be updated with a value that can be supplied to get_prev to get the previous callback object.

If the queue is empty then null is returned.

The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator interface.

### get_next

> static function CB get_next (
> | ref | int | itr,
> | input | T | obj
> )

Returns the next enabled callback of type CB which resides in the queue for obj, using itr as the starting point. If obj is null then the typewide queue for T is searched. itr is the iterator; it will be updated with a value that can be supplied to get_next to get the next callback object.

If no more callbacks exist in the queue, then null is returned. get_next will continue to return null in this case until get_first or get_last has been used to reset the iterator.

The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator interface.

### get_prev

> static function CB get_prev (
> | ref | int | itr,
> | input | T | obj
> )

Returns the previous enabled callback of type CB which resides in the queue for obj, using itr as the starting point. If obj is null then the typewide queue for T is searched. itr is the iterator; it will be updated with a value that can be supplied to get_prev to get the previous callback object.

If no more callbacks exist in the queue, then null is returned. get_prev will continue to return null in this case until get_first or get_last has been used to reset the iterator.

The iterator class uvm_callback_iter may be used as an alternative, simplified, iterator interface.

### Debug

### display

> static function void display(
> | T | obj | = | null
> )

This function displays callback information for obj. If obj is null, then it displays callback information for all objects of type T, including typewide callbacks.

## uvm_callback_iter

The uvm_callback_iter class is an iterator class for iterating over callback queues of a specific callback type. The typical usage of the class is:

>     uvm_callback_iter#(mycomp,mycb) iter = new(this);
>     for(mycb cb = iter.first(); cb != null; cb = iter.next())
>        cb.dosomething();

The callback iteration macros, `uvm_do_callbacks and `uvm_do_callbacks_exit_on provide a simple method for iterating callbacks and executing the callback methods.

Summary

uvm_callback_iter
The uvm_callback_iter class is an iterator class for iterating over callback queues of a specific callback type.
Class Declaration
> class uvm_callback_iter#(
> | type | T | = | uvm_object,
> | type | CB | = | uvm_callback
> )
Methods |
new | Creates a new callback iterator object.
first | Returns the first valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
last | Returns the last valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
next | Returns the next valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
prev | Returns the previous valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.
get_cb | Returns the last callback accessed via a first() or next() call.

### Methods

### new

> function new(
> | T | obj
> )

Creates a new callback iterator object. It is required that the object context be provided.

### first

> function CB first()

Returns the first valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object. If the queue is empty then null is returned.

### last

> function CB last()

Returns the last valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object. If the queue is empty then null is returned.

### next

> function CB next()

Returns the next valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object. If there are no more valid callbacks in the queue, then null is returned.

### prev

> function CB prev()

Returns the previous valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object. If there are no more valid callbacks in the queue, then null is returned.

### get_cb

> function CB get_cb()

Returns the last callback accessed via a first() or next() call.

## uvm_callback

The uvm_callback class is the base class for user-defined callback classes. Typically, the component developer defines an application-specific callback class that extends from this class. In it, he defines one or more virtual methods, called a callback interface, that represent the hooks available for user override.

Methods intended for optional override should not be declared pure. Usually, all the callback methods are defined with empty implementations so users have the option of overriding any or all of them.

The prototypes for each hook method are completely application specific with no restrictions.

Summary

uvm_callback
The uvm_callback class is the base class for user-defined callback classes.
Class Hierarchy
uvm_void
uvm_object
uvm_callback
Class Declaration
> class uvm_callback extends uvm_object
Methods |
new | Creates a new uvm_callback object, giving it an optional name.
callback_mode | Enable/disable callbacks (modeled like rand_mode and constraint_mode).
is_enabled | Returns 1 if the callback is enabled, 0 otherwise.
get_type_name | Returns the type name of this callback object.

### Methods

### new

> function new(
> | string | name | = | "uvm_callback"
> )

Creates a new uvm_callback object, giving it an optional name.

### callback_mode

> function bit callback_mode(
> | int | on | = | -1
> )

Enable/disable callbacks (modeled like rand_mode and constraint_mode).

### is_enabled

> function bit is_enabled()

Returns 1 if the callback is enabled, 0 otherwise.

### get_type_name

> virtual function string get_type_name()

Returns the type name of this callback object.

> class uvm_callbacks #(
> | type | T | = | uvm_object,
> | type | CB | = | uvm_callback
> ) extends uvm_typed_callbacks#(T)

The uvm_callbacks class provides a base class for implementing callbacks, which are typically used to modify or augment component behavior without changing the component class.

> class uvm_callback_iter#(
> | type | T | = | uvm_object,
> | type | CB | = | uvm_callback
> )

The uvm_callback_iter class is an iterator class for iterating over callback queues of a specific callback type.

> class uvm_callback extends uvm_object

The uvm_callback class is the base class for user-defined callback classes.
This type parameter specifies the base callback type that will be managed by this callback class.

> static function void add(
> | T | obj, |  |
> | uvm_callback | cb, |  |
> | uvm_apprepend | ordering | = | UVM_APPEND
> )

Registers the given callback object, cb, with the given obj handle.

> static function void add_by_name(
> | string | name, |  |
> | uvm_callback | cb, |  |
> | uvm_component | root, |  |
> | uvm_apprepend | ordering | = | UVM_APPEND
> )

Registers the given callback object, cb, with one or more uvm_components.

> static function void delete(
> | T | obj,
> | uvm_callback | cb
> )

Deletes the given callback object, cb, from the queue associated with the given obj handle.

> static function void delete_by_name(
> | string | name,
> | uvm_callback | cb,
> | uvm_component | root
> )

Removes the given callback object, cb, associated with one or more uvm_component callback queues.

> static function CB get_first (
> | ref | int | itr,
> | input | T | obj
> )

Returns the first enabled callback of type CB which resides in the queue for obj.

> static function CB get_last (
> | ref | int | itr,
> | input | T | obj
> )

Returns the last enabled callback of type CB which resides in the queue for obj.

> static function CB get_next (
> | ref | int | itr,
> | input | T | obj
> )

Returns the next enabled callback of type CB which resides in the queue for obj, using itr as the starting point.

> static function CB get_prev (
> | ref | int | itr,
> | input | T | obj
> )

Returns the previous enabled callback of type CB which resides in the queue for obj, using itr as the starting point.

> static function void display(
> | T | obj | = | null
> )

This function displays callback information for obj.

> function void find_all (
> |  | string | comp_match, |  |
> | ref | uvm_component | comps[$], |  |
> | input | uvm_component | comp | = | null
> )

Returns the component handle (find) or list of components handles (find_all) matching a given string.

> function new(
> | T | obj
> )

Creates a new callback iterator object.

> function CB first()

Returns the first valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.

> function CB last()

Returns the last valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.

> function CB next()

Returns the next valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.

> function CB prev()

Returns the previous valid (enabled) callback of the callback type (or a derivative) that is in the queue of the context object.

> function CB get_cb()

Returns the last callback accessed via a first() or next() call.

> virtual class uvm_void

The uvm_void class is the base class for all UVM classes.

> virtual class uvm_object extends uvm_void

The uvm_object class is the base class for all UVM data and hierarchical classes.

> function new(
> | string | name | = | "uvm_callback"
> )

Creates a new uvm_callback object, giving it an optional name.

> function bit callback_mode(
> | int | on | = | -1
> )

Enable/disable callbacks (modeled like rand_mode and constraint_mode).

> function bit is_enabled()

Returns 1 if the callback is enabled, 0 otherwise.

> virtual function string get_type_name()

Returns the type name of this callback object.