Re: sc_event_and/or_list

John, All,

I just realized, that the attached files in my previous mail may not be
concise enough to review the proposed API.

  Please find below a stripped-down version of the possible "new" public
interface of the event list related classes.

Greetings from Oldenburg,
  Philipp

namespace sc_core {

// -------------------------------------------------------------------
// CLASS : sc_event_(and|or)_expr
// (implementation defined expression classes, an application shall
// not use these classes explicitly).
// -------------------------------------------------------------------

// AND expressions
class sc_event_and_expr // implementation-defined
{
public:
    operator sc_event_and_list const &() const;
};

sc_event_and_expr
operator & ( sc_event_and_expr, sc_event const & );
sc_event_and_expr
operator & ( sc_event_and_expr, sc_event_and_list const & );

// OR expressions
class sc_event_or_expr
{
public:
    operator sc_event_or_list const &() const;
};

sc_event_or_expr
operator | ( sc_event_or_expr, sc_event const & );
sc_event_or_expr
operator | ( sc_event_or_expr, sc_event_or_list const & );

// -------------------------------------------------------------------
// CLASS : sc_event -> new/changed operators
// -------------------------------------------------------------------

class sc_event
{
public:
     // ...
     sc_event_or_expr operator | ( const sc_event& ) const;
     sc_event_or_expr operator | ( const sc_event_or_list& ) const;

     sc_event_and_expr operator & ( const sc_event& ) const;
     sc_event_and_expr operator & ( const sc_event_and_list& ) const;
};

// -------------------------------------------------------------------
// CLASS : sc_event_or_list
// -------------------------------------------------------------------

class sc_event_or_list
{
public:
    sc_event_or_list(); // default constructible
    sc_event_or_list( const sc_event& ); // single-event list

    void swap( sc_event_or_list& ); // optional
    int size() const; // shall be >0 for wait() etc.

    // modify in-place
    sc_event_or_list& operator |= ( const sc_event& );
    sc_event_or_list& operator |= ( const sc_event_or_list & );

    // non-mutating operators -> return expression
    sc_event_or_expr operator | ( const sc_event& ) const;
    sc_event_or_expr operator | ( const sc_event_or_list& ) const;
};

// -------------------------------------------------------------------
// CLASS : sc_event_and_list (see OR list)
// -------------------------------------------------------------------

class sc_event_and_list
{
public:
    sc_event_and_list();
    sc_event_and_list( const sc_event& );

    void swap( sc_event_and_list& );
    int size() const;

    sc_event_and_list& operator &= ( const sc_event& );
    sc_event_and_list& operator &= ( const sc_event_and_list & );

    sc_event_and_expr operator & ( const sc_event& );
    sc_event_and_expr operator & ( const sc_event_and_list& );
};

} // namespace sc_core

On 12/10/10 19:08, Philipp A. Hartmann wrote:
> John,
>
> sorry for the delay. I finally found some time to look at this.
> Comments embedded below.
>
> On 12/10/10 16:22, john.aynsley@doulos.com wrote:
> [snip]
>
>> Using Philipp's prototype we can do some cool stuff with event lists, for
>> example:
> [snip some code examples]
>
>> sc_event_and_list list3 = list2 & e2; // Caveat - modifies list2
>> wait( list3 );
>
> I agree, that this is an unexpected side-effect. I would suggest to add
> &= and |= operators to the lists to modify lists in place, though:
>
> class sc_event_or_list {
> // ...
> sc_event_or_list& operator |= ( const sc_event& );
> sc_event_or_list& operator |= ( const sc_event_or_list & );
>
> sc_event_or_expr operator | ( const sc_event& ) const;
> sc_event_or_expr operator | ( const sc_event_or_list& ) const;
> };
>
> (sc_event_or_expr is an implementation defined helper class, as you
> suggested, see below).
>
>> However, because the ctor sc_event_and_list(const sc_event&) is protected,
>> we cannot do
>>
>> sc_event_and_list list5 = e3;
>>
>> I think it would be nice to be able to initialize a list with a single
>> event, so I propose we make this ctor public (but without putting the
>> auto_delete argument in the LRM)
>
> I'm not sure, if this is really required. With the '&|='-operators, the
> same could be written as:
>
> sc_event_and_list list5;
> list5 &= e3;
>
> Nevertheless it seems not to cause real harm in the usual case. But
> note, that for your desired syntax these constructors can not be
> 'explicit', which may lead to ambiguities if some functions are
> overloaded for sc_event_and_list and sc_event_or_list but not sc_event
> (not in the kernel, though).
>
>> Also, we cannot do
>>
>> sc_event_and_list list6 = list3 & list4;
>>
>> because we have no sc_event_and_list& operator & ( const
>> sc_event_and_list& );
>> I propose we add this operator
>
> Indeed, this would be very useful. Implemented in the attached quick'n
> dirty prototype as well.
>
>> Finally, note that
>>
>> list2 = list2 & e1;
>>
>> is equivalent to
>>
>> list2 & e1;
>>
>> the latter being permitted because operator& works through a side-effect.
>> Would this be a reason for introducing a separate class for
>> user-instantiated event lists?
>
> Yes, this is a strong reason for adding implementation-defined
> expression helper classes. They can be implemented fairly easily around
> a temporary (auto-deleted) sc_event_list, which gives up ownership upon
> conversion to a list object.
>
> I have attached updated sc_event.(h,cpp) classes, which implement nearly
> all of the proposed extensions:
>
> - construction from single events
> - expression classes (sc_event_and_expr, sc_event_or_expr)
> - list concatenation ( list1 & list2 )
> - operator &=, |=
> - size()
> - swap()
> - move-semantics for temporary lists (implementation detail)
>
> The implementation is backwards-compatible, even regarding the
> 'reference hack' and can detect premature deletion (or modification) of
> busy event lists (i.e. with currently sensitive processes).
>
> The new classes should work with the earlier proposed 'const patch',
> where wait() and next_trigger() take const list-references. This
> earlier patch (against OSCI PoC version 2.3.10dec09_beta) can be found
> in the Twiki [1].
>
> Greetings from Oldenburg,
> Philipp
>
> [1]
> http://www.eda.org/twiki/pub/Main/PhilippHartmann/0001-make-event-handling-const.patch
>

-- 
Philipp A. Hartmann
Hardware/Software Design Methodology Group
OFFIS Institute for Information Technology
R&D Division Transportation · FuE-Bereich Verkehr
Escherweg 2 · 26121 Oldenburg · Germany
Phone/Fax: +49-441-9722-420/282 · PGP: 0x9161A5C0 · http://www.offis.de/
-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.