Changeset e70bfa5 in mainline


Ignore:
Timestamp:
2007-07-02T22:11:54Z (17 years ago)
Author:
Jakub Jermar <jakub@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
f5b4fb9
Parents:
7b63b6b
Message:

Improve comments in async.c

File:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/libc/generic/async.c

    r7b63b6b re70bfa5  
    107107static LIST_INITIALIZE(timeout_list);
    108108
     109/** Structures of this type represent a waiting fibril. */
    109110typedef struct {
    110         /** Expiration time for waiting fibril. */
     111        /** Expiration time. */
    111112        struct timeval expires;         
    112113        /** If true, this struct is in the timeout list. */
    113114        int inlist;
     115        /** Timeout list link. */
    114116        link_t link;
    115117
    116118        /** Fibril waiting for this message. */
    117119        fid_t fid;
    118         /** If this fibril is currently active. */
     120        /** If true, this fibril is currently active. */
    119121        int active;
    120         /** If true, we timed out. */
     122        /** If true, we have timed out. */
    121123        int timedout;
    122124} awaiter_t;
    … …  
    124126typedef struct {
    125127        awaiter_t wdata;
    126 
    127         int done;                       /**< If reply was received */
    128         ipc_call_t *dataptr;            /**< Pointer where the answer data
    129                                          *   is stored */
     128       
     129        /** If reply was received. */
     130        int done;
     131        /** Pointer to where the answer data is stored. */
     132        ipc_call_t *dataptr;
     133
    130134        ipcarg_t retval;
    131135} amsg_t;
    … …  
    140144        awaiter_t wdata;
    141145
    142         link_t link;                    /**< Hash table link. */
    143         ipcarg_t in_phone_hash;         /**< Incoming phone hash. */
    144         link_t msg_queue;               /**< Messages that should be delivered
    145                                          *   to this fibril. */
    146         /* Structures for connection opening packet */
     146        /** Hash table link. */
     147        link_t link;
     148
     149        /** Incoming phone hash. */
     150        ipcarg_t in_phone_hash;         
     151
     152        /** Messages that should be delivered to this fibril. */
     153        link_t msg_queue;               
     154                                         
     155        /** Identification of the opening call. */
    147156        ipc_callid_t callid;
     157        /** Call data of the opening call. */
    148158        ipc_call_t call;
    149         ipc_callid_t close_callid;      /* Identification of closing packet. */
     159
     160        /** Identification of the closing call. */
     161        ipc_callid_t close_callid;
     162
     163        /** Fibril function that will be used to handle the connection. */
    150164        void (*cfibril)(ipc_callid_t, ipc_call_t *);
    151165} connection_t;
    … …  
    153167/** Identifier of the incoming connection handled by the current fibril. */
    154168__thread connection_t *FIBRIL_connection;
    155 /** If true, it is forbidden to use async_req functions and
    156  *  all preemption is disabled */
     169
     170/** If true, it is forbidden to use async_req functions and all preemption is
     171 * disabled. */
    157172__thread int in_interrupt_handler;
    158173
    … …  
    162177static async_client_conn_t interrupt_received = default_interrupt_received;
    163178
    164 /* Hash table functions */
    165179#define CONN_HASH_TABLE_CHAINS  32
    166180
     181/** Compute hash into the connection hash table based on the source phone hash.
     182 *
     183 * @param key           Pointer to source phone hash.
     184 *
     185 * @return              Index into the connection hash table.
     186 */
    167187static hash_index_t conn_hash(unsigned long *key)
    168188{
    … …  
    171191}
    172192
     193/** Compare hash table item with a key.
     194 *
     195 * @param key           Array containing the source phone hash as the only item.
     196 * @param keys          Expected 1 but ignored.
     197 * @param item          Connection hash table item.
     198 *
     199 * @return              True on match, false otherwise.
     200 */
    173201static int conn_compare(unsigned long key[], hash_count_t keys, link_t *item)
    174202{
    … …  
    180208}
    181209
     210/** Connection hash table removal callback function.
     211 *
     212 * This function is called whenever a connection is removed from the connection
     213 * hash table.
     214 *
     215 * @param item          Connection hash table item being removed.
     216 */
    182217static void conn_remove(link_t *item)
    183218{
    … …  
    186221
    187222
    188 /** Operations for NS hash table. */
     223/** Operations for the connection hash table. */
    189224static hash_table_operations_t conn_hash_table_ops = {
    190225        .hash = conn_hash,
    … …  
    193228};
    194229
    195 /** Insert sort timeout msg into timeouts list
    196  *
     230/** Sort in current fibril's timeout request.
     231 *
     232 * @param wd            Wait data of the current fibril.
    197233 */
    198234static void insert_timeout(awaiter_t *wd)
    … …  
    214250}
    215251
    216 /** Try to route a call to an appropriate connection fibril
     252/** Try to route a call to an appropriate connection fibril.
    217253 *
    218254 */
    … …  
    258294}
    259295
    260 /** Return new incoming message for the current (fibril-local) connection */
     296/** Return new incoming message for the current (fibril-local) connection.
     297 *
     298 * @param call          Storage where the incoming call data will be stored.
     299 * @param usecs         Timeout in microseconds. Zero denotes no timeout.
     300 *
     301 * @return              If no timeout was specified, then a hash of the
     302 *                      incoming call is returned. If a timeout is specified,
     303 *                      then a hash of the incoming call is returned unless
     304 *                      the timeout expires prior to receiving a message. In
     305 *                      that case zero is returned.
     306 */
    261307ipc_callid_t async_get_call_timeout(ipc_call_t *call, suseconds_t usecs)
    262308{
    … …  
    281327                conn->wdata.inlist = 0;
    282328        }
    283         /* If nothing in queue, wait until something appears */
     329        /* If nothing in queue, wait until something arrives */
    284330        while (list_empty(&conn->msg_queue)) {
    285331                if (usecs)
    … …  
    288334                conn->wdata.active = 0;
    289335                fibril_schedule_next_adv(FIBRIL_TO_MANAGER);
    290                 /* Futex is up after getting back from async_manager
    291                  * get it again */
     336                /*
     337                 * Futex is up after getting back from async_manager get it
     338                 * again.
     339                */
    292340                futex_down(&async_futex);
    293341                if (usecs && conn->wdata.timedout &&
    294342                    list_empty(&conn->msg_queue)) {
    295                         /* If we timed out-> exit */
     343                        /* If we timed out -> exit */
    296344                        futex_up(&async_futex);
    297345                        return 0;
    … …  
    311359/** Fibril function that gets created on new connection
    312360 *
    313  * This function is defined as a weak symbol - to be redefined in
    314  * user code.
     361 * This function is defined as a weak symbol - to be redefined in user code.
    315362 */
    316363static void default_client_connection(ipc_callid_t callid, ipc_call_t *call)
Note: See TracChangeset for help on using the changeset viewer.