RE: Named events

John,

Your summary is nice and accurate.

Comments/answers below.

________________________________
From: john.aynsley@doulos.com [mailto:john.aynsley@doulos.com]
Sent: Monday, November 15, 2010 5:59 PM
To: Bishnupriya Bhattacharya; systemc-p1666-technical@eda.org
Subject: Re: Named events

Bishnupriya,

To summarize the proposal, I think you are saying:

* Events are not sc_objects

* Static events are named
* Dynamic events can be named or unnamed
* Kernel events are unnamed

* Named events share the same namespace (not a C++ namespace) as the object hierarchy. An event name shall not clash with an object name
* The prefix to each event's name is the hierarchical name of the event's parent in the object hierarchy

* There are methods get_child_events, get_top_level_events, and sc_find_event that mirror the methods of the object hierarchy

Comments/questions:

Presumably get_child_objects() does not return any events?

>>> [bpriya: no]

Why not make the namespace of sc_objects and the namespace of sc_events separate? I do not much like having these two different kinds of animal pushed into the same namespace. It seems odd to pollute the namespace of sc_objects with things that are not sc_objects, and then have those things invisible from the point-of-view of the object hierarchy (get_child_objects).

>>> [bpriya: I see your point, but do not agree. The reason for keeping the same namespace for events and objects is simple - intuitiveness and lack of confusion. Inside a module, if a user has both an event named foo and a signal named foo, it is inherently confusing, and moreover, what does it buy the user? The fact that get_child_objects() does not return a sc_event is also simple - because an event is not an object, so there is no sc_object* pointer that can be returned for a sc_event.]

Alternatively, why not derive sc_event from sc_object (making events part of the object hierarchy proper) and add a lightweight variant to the sc_object, where a lightweight sc_object is unnamed and is excluded from the object hierarchy. Then we only need one unified namespace for events and sc_objects. By default, sc_event would be the only example of a lightweight sc_object, but applications could derive new lightweight sc_objects from sc_object. (If performance is an issue, I guess sc_object could become a template where the default is a heavyweight object.)

>>> [bpriya: I would need specifics of the lightweight sc_object variant to fully analyse the proposal. One data point - Cadence has done actual experiments deriving sc_event from sc_object (as it now stands), and encountered performance degradation. Hence, the alternate proposal.]

Thanks,
-Bishnupriya

Just an idea.

John A

From: john.aynsley@doulos.com
To: systemc-p1666-technical@eda.org
Cc: bpriya@cadence.com
Date: 15/11/2010 11:56
Subject: Named events
Sent by: owner-systemc-p1666-technical@eda.org

________________________________

All,

The race is now on to get all the enhancements finished by the end of November.

The final enhancement on our priority list is named events. I include Cadence's proposal below.

Comments please

John A

-----

John, All,

In response to ST's enhancement request presented in this forum, below is a proposal from Cadence for naming sc_events. In this proposal sc_event does not derive from sc_object for performance concerns. One concern is sc_events are meant to be lightweight objects, and deriving from sc_object can make it too heavyweight.

Three categories of events are considered in the proposal:

- 'static' events created up to and including phase start_of_simulation
- 'dynamic' events created after phase start_of_simulation
- kernel events that are directly or indirectly specified in the LRM (e.g. posedge_event of sc_signal<bool>)

The proposal aims to provide a simple, consistent set of rules aligned with sc_object naming semantics, and also keeping in mind performance considerations.

The detailed proposal is given below.

Thanks,
-Bishnupriya

class sc_event {
public:
....
 sc_event(); <-------------- existing
 sc_event(const char* nm); <------------ new
 const char* name() const; <------------ new
 ...
};

1) constructors and hierarchical name of sc_event
  ==============================================

a) static events - created up to and including phase start_of_simulation
  ---------------------------------------------------------------------

Before simulation starts running, both constructors shall register the sc_event as part of the event hierarchy and shall construct a hierarchical name for the event using the string name passed as an argument. Calling the constructor sc_event(const char*) with an empty string shall have the same behavior as the default constructor, that is, the string name shall be set to "event".

A hierarchical name shall be composed of a set of string names separated by the period character '.', starting with the string name of a top-level sc_object instance and including the string name of each module instance or process instance descending down through the object hierarchy until the current sc_event is reached. The hierarchical name shall end with the string name of the sc_event itself.

Hierarchical names are case-sensitive.

It shall be an error if a string name includes the period character (.) or any white-space characters. It is strongly recommended that an application limit the character set of a string name to the following:
a) The lower-case letters a-z
b) The upper-case letters A-Z
c) The decimal digits 0-9
d) The underscore character _

An implementation may generate a warning if a string name contains characters outside this set but is not obliged to do so.

There shall be a single global namespace for hierarchical names of objects and events. Each sc_object and sc_event shall have a unique nonempty hierarchical name. An implementation shall not add any names to this namespace other than the hierarchical names of sc_objects and sc_events explicitly constructed by an application.

The sc_event constructor shall build a hierarchical name from the string name (either passed in as an argument or the default name "event") and test whether that hierarchical name is unique in the global namespace consisting of objects and events. If it is unique, that hierarchical name shall become the hierarchical name of the event. If not, the constructor shall call function
sc_gen_unique_name, passing the string name as a seed. It shall use the value returned as a replacement for the string name and shall repeat this process until a unique hierarchical name is generated. If function sc_gen_unique_name is called more than once in the course of constructing any given sc_object, the choice of seed passed to sc_gen_unique_name on the second and subsequent calls shall be implementation-defined but shall in any case be either the string name passed as the seed on the first such call or shall be one of the string names returned from sc_gen_unique_name in the course of constructing the given sc_event. In other words, the final string name shall have the original string name as a prefix.

If the constructor needs to substitute a new string name in place of the original string name as the result of a name clash, the constructor shall generate a single warning.

b) Dynamic events - created after phase start_of_simulation
  ---------------------------------------------------------

After simulation starts running, there can be a run-time performance impact associated with hierarchically naming an event, e.g.,in the case of a dynamically spawned process with a local event where the process comes and goes repeatedly. To address this performance concern, the behavior of sc_event's default ctor after simulation start is kept unspecified, i.e. implemenntation-defined. An implementation may choose to treat such events exactly the same as static events, or it can choose to not name them at all, or somewhere in between.

The behavior of the second constructor for dynamic events shall be the same as that for static events, i.e. if the user explicitly names a dynamic event, it shall be a part of the event hierarchy, and it shall have a proper hierarchical name following the same rules as in 1a). Calling the constructor sc_event(const char*) with an empty string shall have the same behavior as the default constructor, i.e the behavior is left implementation-dependent.

c) Kernel events
  ---------------

There are events created by the SystemC kernel for various purposes. These events can be classified into two categories

i) Events that are directly or indirectly specified in the LRM, e.g. LRM specifies "const sc_event& sc_signal<bool>::posedge_event()". Lets call these explicit kernel events.

ii) Events that kernel creates for internal implementation. Lets call these implementation kernel events

For implementation kernel events, the implementation is obliged to exclude those events from the event hierarchy and from the namespace of hierarchical names. This would necessitate an extension to the semantics of class sc_event, and the implementation would be obliged to make such an extension transparent to the application.

For explicit kernel events also, the implementation is obliged to exclude such events from the event hierarchy, and from the namespace of hierarchical names, thus not polluting the global namespace. This implies if get_child_events() is invoked on the parent scope of an explicit kernel event, the returned vector shall not contain a reference to the explicit kernel event. Furthermore, the user is always free to name his own application event as he chooses to, without having to worry about his event clashing with an explicit kernel event.

2) obtaining the name of a sc_event
  ================================

const char* sc_event::name() const;

Member function name shall return the hierarchical name of the sc_event instance in the event
hierarchy.

3) add member method to retrieve a list of sc_events from parent scope
  ===================================================================

add member method to sc_module, and sc_process_handle, as below:

 const std::vector<sc_event*>& get_child_events() const;

Member function get_child_events shall return a std::vector containing a pointer to every instance of class sc_event that lies within the module/process in the design hierarchy.

NOTE 1-The phrase within a module does not include instances nested within modules instances but only includes the immediate children of the given module.

4) add global functions to retrieve top-level events and to find event by name
  =============================================================================

namespace sc_core {
 const std::vector<sc_event*>& get_top_level_events() const;
 sc_event* sc_find_event(const char* name);
};

Function sc_get_top_level_events shall return a std::vector containing pointers to all of the toplevel sc_events.

Function sc_find_event shall return a pointer to the sc_event that has a hierarchical name that
exactly matches the value of the string argument or shall return the null pointer if there is no
sc_event having a matching name.

--
This message has been scanned for viruses and
dangerous content by MailScanner<http://www.mailscanner.info/>, and is
believed to be clean.
-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.