/* --COPYRIGHT--,ESD
 *  Copyright (c) 2008-2019 Texas Instruments Incorporated
 *  This program and the accompanying materials are made available under the
 *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
 *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
 *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
 *  Distribution License is available at
 *  http://www.eclipse.org/org/documents/edl-v10.php.
 *
 *  Contributors:
 *      Texas Instruments - initial implementation
 * --/COPYRIGHT--*/
/*
 *  ======== IGateProvider.xdc ========
 */
package xdc.runtime

/*!
 *  ======== IGateProvider ========
 *  Interface implemented by all gate providers
 *
 *  Gates are used within the `xdc.runtime` package to serialize access
 *  to data structures that are used by more than one thread.
 *
 *  Gates are responsible for ensuring that only one out of multiple threads
 *  can access a data structure at a time.  There are important scheduling
 *  latency and performance considerations that affect the "type" of gate used
 *  to protect each data structure.  For example, the best way to protect a
 *  shared counter is to simply disable all interrupts before the update and
 *  restore the interrupt state after the update; disabling all interrupts
 *  prevents all thread switching, so the update is guaranteed to be "atomic".
 *  Although highly efficient, this  method of creating atomic sections causes
 *  serious system latencies when the time required to update the data structure
 *  can't be bounded.
 *
 *  For example, a memory manager's list of free blocks can grow indefinitely
 *  long during periods of high fragmentation.  Searching such a list with
 *  interrupts disabled would cause system latencies to also become unbounded.
 *  In this case, the best solution is to provide a gate that suspends the
 *  execution of threads that try to enter a gate that has already been entered;
 *  i.e., the gate "blocks" the thread until the thread already in the gate
 *  leaves.  The time required to enter and leave the gate is greater than simply 
 *  enabling and restoring interrupts, but since the time spent within the gate is
 *  relatively large, the overhead caused by entering and leaving gates will not
 *  become a significant percentage of overall system time.  More importantly,
 *  threads that do not need to access the shared data structure are completely
 *  unaffected by threads that do access it.
 *
 *  @a(Notes)
 *  Modules inheriting this interface should treat all names beginning with
 *  `Q_` as reserved words, i.e. the names from that namespace should not
 *  be used.  This will allow future version of this interface to define new
 *  constants ("qualities" ) similar to `{@link #Q_BLOCKING}` and
 *  `{@link #Q_PREEMPTING}` without breaking any existing modules.
 */
@DirectCall
interface IGateProvider {

    /*!
     *  ======== Q_BLOCKING ========
     *  Blocking quality
     *
     *  Gates with this "quality" may cause the calling thread to block;
     *  i.e., suspend execution until another thread leaves the gate.
     */
    /* REQ_TAG(SYSBIOS-925) */
    const Int Q_BLOCKING = 1;

    /*!
     *  ======== Q_PREEMPTING ========
     *  Preempting quality
     *
     *  Gates with this "quality" allow other threads to preempt the thread
     *  that has already entered the gate.
     */
    /* REQ_TAG(SYSBIOS-926) */
    const Int Q_PREEMPTING = 2;

    /*!
     *  ======== query ========
     *  Configuration time test for a particular gate quality
     *
     *  @param(qual)    constant describing a quality
     *  @a(returns)     Returns `TRUE` if the gate has the given quality,
     *  and `FALSE` otherwise, which includes the case when the gate does not
     *  recognize the constant describing the quality.
     */
    metaonly Bool queryMeta(Int qual);

    /*!
     *  ======== query ========
     *  Runtime test for a particular gate quality
     *
     *  @param(qual)    constant describing a quality
     *  @a(returns)     Returns `TRUE` if the gate has the given quality,
     *  and `FALSE` otherwise, which includes the case when the gate does not
     *  recognize the constant describing the quality.
     */
    /* REQ_TAG(SYSBIOS-927) */
    Bool query(Int qual);

instance:

    /*!
     *  ======== create ========
     *  Create a gate instance
     */
    create();

    /*!
     *  ======== enter ========
     *  Enter this gate
     *
     *  Each gate provider can implement mutual exclusion using different
     *  algorithms; e.g., disabling all scheduling, disabling the scheduling
     *  of all threads below a specified "priority level", suspending the caller
     *  when the gate has been entered by another thread and re-enabling it when
     *  the the other thread leaves the gate.  However, in all cases, after this
     *  method returns that caller has exclusive access to the data protected by
     *  this gate.
     *
     *  A thread may reenter a gate without blocking or failing.
     *
     *  @a(returns)
     *  Returns a "key" that is used to `{@link #leave}` this gate; this value
     *  is used to restore thread preemption to the state that existed just
     *  prior to entering this gate.
     */
    IArg enter();

    /*!
     *  ======== leave ========
     *  Leave this gate
     *
     *  This method is only called by threads that have previously entered this
     *  gate via `{@link #enter}`.  After this method returns, the caller must
     *  not access the data structure protected by this gate (unless the caller
     *  has entered the gate more than once and other calls to `leave` remain
     *  to balance the number of previous calls to `enter`).
     *
     *  @param(key) the value returned by a matching call to `{@link #enter}`
     */
    Void leave(IArg key);
}