1    /* 
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved. 
     3     *  This program and the accompanying materials are made available under the 
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at 
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== Sync.xdc ========
    15     */
    16    import xdc.runtime.Error;
    17    import xdc.runtime.Assert;
    18    import xdc.runtime.knl.ISync;
    19    
    20    /*!
    21     *  ======== Sync ========
    22     *  Provides synchronization APIs when an ISync.Handle is available.
    23     *
    24     *  The application must first obtain an ISync.Handle. 
    25     *  It can get such a handle by directly calling {@link SyncGeneric#create} or 
    26     *  {@link SyncSemThread#create}. Then the application can use the generic 
    27     *  APIs provided by this module.
    28     */
    29    
    30    module Sync
    31    {
    32        /*!
    33         *  ======== WaitStatus ========
    34         *  Error codes returned by Sync_wait
    35         */
    36        enum WaitStatus {
    37            WaitStatus_ERROR = -1,
    38            WaitStatus_TIMEOUT = 0,
    39            WaitStatus_SUCCESS = 1
    40        };
    41        
    42        /*! Used to wait forever */
    43        const UInt WAIT_FOREVER = ISync.WAIT_FOREVER;
    44    
    45        /*! Used to specify no waiting */
    46        const UInt NO_WAIT = ISync.NO_WAIT;
    47    
    48        /*!
    49         *  Proxy used for optimization.
    50         *
    51         *  If ALL ISync.Handles were created using the same module 
    52         *  (e.g SyncSemProcess) then setting this Proxy to SyncSemProcess and 
    53         *  setting Sync.Proxy.abstractInstances$ = false, 
    54         *  Sync APIs can have better performance.
    55         */
    56        proxy Proxy inherits ISync;
    57    
    58        /*!
    59         *  ======== query ========
    60         *  Query for a particular quality.
    61         *
    62         *  FALSE is returned if quality not supported.
    63         *
    64         *  @param(sync)    sync handle
    65         *  @param(qual)    quality
    66         *  @b(returns)     TRUE or FALSE.
    67         */
    68        Bool query(ISync.Handle sync, Int qual);
    69    
    70        /*!
    71         *  ======== signal ========
    72         *  Called at completion of an activity.
    73         *
    74         *  This function is non-blocking. It is also required that the underlying
    75         *  sync be binary in nature.
    76         *
    77         *  @param(sync)    sync handle
    78         */
    79        Void signal(ISync.Handle sync);
    80    
    81        /*!
    82         *  ======== wait ========
    83         *  Called to wait/poll for completion of an activity.
    84         *
    85         *  This function can block. Non-blocking implementations should return
    86         *  ;
    87         *  Wait for the semaphore to become available.
    88         *
    89         *  @p(blist)
    90         *  -{@link #WaitStatus_ERROR} if an error occured.
    91         *  -{@link #WaitStatus_TIMEOUT} denotes timeout.
    92         *  -{@link #WaitStatus_SUCCESS} semaphore was decremented. 
    93         *  @p
    94         *
    95         *  @param(sync)        sync handle
    96         *  @param(timeout)     timeout in microseconds
    97         *  @b(returns)         see description above
    98         */
    99        Int wait(ISync.Handle sync, UInt timeout, Error.Block *eb);
   100    }
   101    /*
   102     *  @(#) xdc.runtime.knl; 1, 0, 0,98; 8-20-2010 17:21:08; /db/ztree/library/trees/xdc/xdc-v48x/src/packages/
   103     */
   104