1    /* --COPYRIGHT--,ESD
     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     * --/COPYRIGHT--*/
    13    /*
    14     *  ======== Semaphore.xdc ========
    15     */
    16    
    17    import xdc.runtime.Assert;
    18    import xdc.runtime.Error;
    19    import xdc.runtime.knl.ISemaphore;
    20    
    21    /*!
    22     *  ======== Semaphore ========
    23     *  Provides semaphore services when an ISemaphore.Handle is available. 
    24     *  [EXPERIMENTAL]
    25     *  
    26     *  An application can isolate itself from ISemaphore implementations by using 
    27     *  this module. The application must first obtain an ISemaphore.Handle. 
    28     *  It make get such a handle by directly calling {@link SemThread#create} or 
    29     *  {@link SemProcess#create}. Then the application can use the generic 
    30     *  APIs provided by this module.
    31     */
    32    
    33    module Semaphore
    34    {
    35        /*!
    36         *  ======== PendStatus ========
    37         *  Error codes returned by Semaphore_pend
    38         */
    39        enum PendStatus {
    40            PendStatus_ERROR = -1,
    41            PendStatus_TIMEOUT = 0,
    42            PendStatus_SUCCESS = 1
    43        };
    44    
    45        /*! Used as the timeout value to specify wait forever */
    46        const UInt FOREVER = ISemaphore.FOREVER;
    47        
    48        /*!
    49         *  Proxy used for optimization.
    50         *
    51         *  If ALL ISemaphore.Handles were created using the same module 
    52         *  (e.g SemProcess) then setting this Proxy to SemProcess and 
    53         *  setting Semaphore.Proxy.abstractInstances$ = false, 
    54         *  Semaphore APIs can have better performance.
    55         */
    56        proxy Proxy inherits ISemaphore;
    57    
    58        /*!
    59         *  ======== pend ========
    60         *  Wait for the semaphore to have a nonzero count, then decrement it.
    61         *
    62         *  @p(blist)
    63         *  -{@link #PendStatus_ERROR} if an error occured.
    64         *  -{@link #PendStatus_TIMEOUT} denotes timeout.
    65         *  -{@link #PendStatus_SUCCESS} semaphore was decremented. 
    66         *    details.
    67         *  @p
    68         *
    69         *  @param(sem)     ISemaphore.Handle to be used
    70         *  @param(timeout) timeout in microseconds
    71         *  @param(eb)      Pointer to Error.Block
    72         *  @a(returns)     status returned. (refer to above description)
    73         */
    74        Int pend(ISemaphore.Handle sem, UInt timeout, Error.Block *eb);
    75    
    76        /*!
    77         *  ======== post ========
    78         *  Increment the semaphore count.
    79         *
    80         *  @param(sem)     ISemaphore.Handle to be used
    81         *  @param(eb)      Pointer to Error.Block
    82         *  @a(returns)     true for success, false for error in Error block.  
    83         */
    84        Bool post(ISemaphore.Handle sem, Error.Block *eb);
    85    }
    86    
    87    /*
    88     *! Revision History
    89     *! ================
    90     *! 17-Apr-2009 nitya    Review updates
    91     */
    92    /*
    93     *  @(#) xdc.runtime.knl; 1, 0, 0,24; 9-3-2009 11:42:01; /db/ztree/library/trees/xdc-t57x/src/packages/
    94     */
    95