Navigation


Ignore:
Timestamp:
Sep 18, 2009, 6:54:07 PM (15 years ago)
Author:
Sebastien Decugis <sdecugis@nict.go.jp>
Branch:
default
Phase:
public
Message:

Backup for the week-end

File:
1 edited

Legend:

Unmodified
Added
Removed

  • include/freeDiameter/libfreeDiameter.h

    r7 r8  
    3737 *
    3838 * This library is meant to be used by both the freeDiameter daemon and its extensions.
    39  *
    4039 * It provides the tools to manipulate Diameter messages and related data.
    41  *
    4240 * This file should always be included as #include <freeDiameter/libfreeDiameter.h>
     41 *
     42 * The file contains the following parts:
     43 *      DEBUG
     44 *      MACROS
     45 *      THREADS
     46 *      LISTS
     47 *      DICTIONARY
     48 *      SESSIONS
     49 *      MESSAGES
     50 *      DISPATCH
     51 *      QUEUES
    4352 */
    4453
    … …  
    297306#define sSA6    struct sockaddr_in6
    298307
    299 /* Dump one sockaddr */
    300 #define sSA_DUMP( level, text, sa ) {                           \
     308/* Dump one sockaddr Node information */
     309#define sSA_DUMP_NODE( sa, flag ) {                             \
    301310        sSA * __sa = (sSA *)(sa);                               \
    302         char *__str, __addrbuf[INET6_ADDRSTRLEN];               \
     311        char __addrbuf[INET6_ADDRSTRLEN];                       \
    303312        if (__sa) {                                             \
    304313          int __rc = getnameinfo(__sa,                          \
    … …  
    308317                        NULL,                                   \
    309318                        0,                                      \
    310                         0);                                     \
     319                        flag);                                  \
    311320          if (__rc)                                             \
    312                 __str = (char *)gai_strerror(__rc);             \
     321                fd_log_debug((char *)gai_strerror(__rc));       \
    313322          else                                                  \
    314                 __str = &__addrbuf[0];                          \
     323                fd_log_debug(&__addrbuf[0]);                    \
    315324        } else {                                                \
    316                 __str = "(NULL / ANY)";                         \
     325                fd_log_debug("(NULL / ANY)");                   \
    317326        }                                                       \
    318         TRACE_DEBUG(level, text "%s", __str);                   \
    319327}
     328/* if needed, add sSA_DUMP_SERVICE */
    320329
    321330/* The sockaddr length of a sSS structure */
    … …  
    22752284
    22762285/*============================================================*/
    2277 /*                    MESSAGE QUEUES                          */
     2286/*                     QUEUES                                 */
    22782287/*============================================================*/
    22792288
    2280 /* Management of queues of messages */
    2281 
    2282 /* A message queue is an opaque object */
    2283 struct mqueue;
    2284 
    2285 /*
    2286  * FUNCTION:    fd_mq_new
    2287  *
    2288  * PARAMETERS:
    2289  *  queue       : Upon success, a pointer to the new message queue is saved here.
    2290  *
    2291  * DESCRIPTION:
    2292  *  Create a new empty message queue.
     2289/* Management of FIFO queues of elements */
     2290
     2291/* A queue is an opaque object */
     2292struct fifo;
     2293
     2294/*
     2295 * FUNCTION:    fd_fifo_new
     2296 *
     2297 * PARAMETERS:
     2298 *  queue       : Upon success, a pointer to the new queue is saved here.
     2299 *
     2300 * DESCRIPTION:
     2301 *  Create a new empty queue.
    22932302 *
    22942303 * RETURN VALUE :
    2295  *  0           : The message queue has been initialized successfully.
     2304 *  0           : The queue has been initialized successfully.
    22962305 *  EINVAL      : The parameter is invalid.
    22972306 *  ENOMEM      : Not enough memory to complete the creation. 
    22982307 */
    2299 int fd_mq_new ( struct mqueue ** queue );
    2300 
    2301 /*
    2302  * FUNCTION:    fd_mq_del
    2303  *
    2304  * PARAMETERS:
    2305  *  queue       : Pointer to an empty message queue to delete.
    2306  *
    2307  * DESCRIPTION:
    2308  *  Destroys a message queue. This is only possible if no thread is waiting for a message,
     2308int fd_fifo_new ( struct fifo ** queue );
     2309
     2310/*
     2311 * FUNCTION:    fd_fifo_del
     2312 *
     2313 * PARAMETERS:
     2314 *  queue       : Pointer to an empty queue to delete.
     2315 *
     2316 * DESCRIPTION:
     2317 *  Destroys a queue. This is only possible if no thread is waiting for an element,
    23092318 * and the queue is empty.
    23102319 *
    23112320 * RETURN VALUE:
    2312  *  0           : The message queue has been destroyed successfully.
     2321 *  0           : The queue has been destroyed successfully.
    23132322 *  EINVAL      : The parameter is invalid.
    23142323 */
    2315 int fd_mq_del ( struct mqueue  ** queue );
    2316 
    2317 /*
    2318  * FUNCTION:    fd_mq_length
    2319  *
    2320  * PARAMETERS:
    2321  *  queue       : The queue from which to retrieve the length.
    2322  *  length      : Upon success, the current number of messages in the queue is stored here.
    2323  *
    2324  * DESCRIPTION:
    2325  *  Retrieve the number of messages pending in a queue.
     2324int fd_fifo_del ( struct fifo  ** queue );
     2325
     2326/*
     2327 * FUNCTION:    fd_fifo_length
     2328 *
     2329 * PARAMETERS:
     2330 *  queue       : The queue from which to retrieve the number of elements.
     2331 *  length      : Upon success, the current number of elements in the queue is stored here.
     2332 *
     2333 * DESCRIPTION:
     2334 *  Retrieve the number of elements in a queue.
    23262335 *
    23272336 * RETURN VALUE:
    … …  
    23292338 *  EINVAL      : A parameter is invalid.
    23302339 */
    2331 int fd_mq_length ( struct mqueue * queue, int * length );
    2332 int fd_mq_length_noerr ( struct mqueue * queue ); /* alternate with no error checking */
    2333 
    2334 /*
    2335  * FUNCTION:    fd_mq_setthrhd
     2340int fd_fifo_length ( struct fifo * queue, int * length );
     2341int fd_fifo_length_noerr ( struct fifo * queue ); /* no error checking version */
     2342
     2343/*
     2344 * FUNCTION:    fd_fifo_setthrhd
    23362345 *
    23372346 * PARAMETERS:
    … …  
    23452354 * DESCRIPTION:
    23462355 *  This function allows to adjust the number of producer / consumer threads of a queue.
    2347  * If the consumer are slower than the producers, the number of messages in the queue increase.
     2356 * If the consumer are slower than the producers, the number of elements in the queue increase.
    23482357 * By setting a "high" value, we allow a callback to be called when this number is too high.
    23492358 * The typical use would be to create an additional consumer thread in this callback.
    23502359 * If the queue continues to grow, the callback will be called again when the length is 2 * high, then 3*high, ... N * high
    2351  * (the callback itself may implement a limit on the number of consumers that can be created)
     2360 * (the callback itself should implement a limit on the number of consumers that can be created)
    23522361 * When the queue starts to decrease, and the number of elements go under ((N - 1) * high + low, the l_cb callback is called
    2353  * and would typially stop one of the consumer threads. If the queue continue to reduce, l_cb is again called at (N-2)*high + low,
     2362 * and would typially stop one of the consumer threads. If the queue continues to reduce, l_cb is again called at (N-2)*high + low,
    23542363 * and so on.
    23552364 *
    … …  
    23572366 * l_cb when the length of the queue is becoming < low.
    23582367 *
    2359  * Note that the callbacks are called synchronously, during fd_mq_post or fd_mq_get. Their operation should be quick.
     2368 * Note that the callbacks are called synchronously, during fd_fifo_post or fd_fifo_get. Their operation should be quick.
    23602369 *
    23612370 * RETURN VALUE:
    … …  
    23632372 *  EINVAL      : A parameter is invalid.
    23642373 */
    2365 int fd_mq_setthrhd ( struct mqueue * queue, void * data, uint16_t high, void (*h_cb)(struct mqueue *, void **), uint16_t low, void (*l_cb)(struct mqueue *, void **) );
    2366 
    2367 /*
    2368  * FUNCTION:    fd_mq_post
    2369  *
    2370  * PARAMETERS:
    2371  *  queue       : The queue in which the message must be posted.
    2372  *  msg         : The message that is put in the queue.
    2373  *
    2374  * DESCRIPTION:
    2375  *  A message is added in a queue. Messages are retrieved from the queue (in FIFO order)
    2376  *  with the fd_mq_get, fd_mq_tryget, or fd_mq_timedget functions.
    2377  *
    2378  * RETURN VALUE:
    2379  *  0           : The message is queued.
     2374int fd_fifo_setthrhd ( struct fifo * queue, void * data, uint16_t high, void (*h_cb)(struct fifo *, void **), uint16_t low, void (*l_cb)(struct fifo *, void **) );
     2375
     2376/*
     2377 * FUNCTION:    fd_fifo_post
     2378 *
     2379 * PARAMETERS:
     2380 *  queue       : The queue in which the element must be posted.
     2381 *  item        : The element that is put in the queue.
     2382 *
     2383 * DESCRIPTION:
     2384 *  An element is added in a queue. Elements are retrieved from the queue in FIFO order
     2385 *  with the fd_fifo_get, fd_fifo_tryget, or fd_fifo_timedget functions.
     2386 *
     2387 * RETURN VALUE:
     2388 *  0           : The element is queued.
    23802389 *  EINVAL      : A parameter is invalid.
    23812390 *  ENOMEM      : Not enough memory to complete the operation.
    23822391 */
    2383 int fd_mq_post ( struct mqueue * queue, struct msg ** msg );
    2384 
    2385 /*
    2386  * FUNCTION:    fd_mq_get
    2387  *
    2388  * PARAMETERS:
    2389  *  queue       : The queue from which the message must be retrieved.
    2390  *  msg         : On return, the first message of the queue is stored here.
    2391  *
    2392  * DESCRIPTION:
    2393  *  This function retrieves a message from a queue. If the queue is empty, the function will block the
    2394  * thread until a new message is posted to the queue, or until the thread is canceled (in which case the
     2392int fd_fifo_post_int ( struct fifo * queue, void ** item );
     2393#define fd_fifo_post(queue, item) \
     2394        fd_fifo_post_int((queue), (void *)(item))
     2395
     2396/*
     2397 * FUNCTION:    fd_fifo_get
     2398 *
     2399 * PARAMETERS:
     2400 *  queue       : The queue from which the first element must be retrieved.
     2401 *  item        : On return, the first element of the queue is stored here.
     2402 *
     2403 * DESCRIPTION:
     2404 *  This function retrieves the first element from a queue. If the queue is empty, the function will block the
     2405 * thread until a new element is posted to the queue, or until the thread is canceled (in which case the
    23952406 * function does not return).
    23962407 *
    23972408 * RETURN VALUE:
    2398  *  0           : A new message has been retrieved.
    2399  *  EINVAL      : A parameter is invalid.
    2400  */
    2401 int fd_mq_get ( struct mqueue * queue, struct msg ** msg );
    2402 
    2403 /*
    2404  * FUNCTION:    fd_mq_tryget
    2405  *
    2406  * PARAMETERS:
    2407  *  queue       : The queue from which the message must be retrieved.
     2409 *  0           : A new element has been retrieved.
     2410 *  EINVAL      : A parameter is invalid.
     2411 */
     2412int fd_fifo_get_int ( struct fifo * queue, void ** item );
     2413#define fd_fifo_get(queue, item) \
     2414        fd_fifo_get_int((queue), (void *)(item))
     2415
     2416/*
     2417 * FUNCTION:    fd_fifo_tryget
     2418 *
     2419 * PARAMETERS:
     2420 *  queue       : The queue from which the element must be retrieved.
    24082421 *  msg         : On return, the message is stored here.
    24092422 *
    24102423 * DESCRIPTION:
    2411  *  This function is similar to fd_mq_get, except that it will not block if
     2424 *  This function is similar to fd_fifo_get, except that it will not block if
    24122425 * the queue is empty, but return EWOULDBLOCK instead.
    24132426 *
    24142427 * RETURN VALUE:
    2415  *  0           : A new message has been retrieved.
     2428 *  0           : A new element has been retrieved.
    24162429 *  EINVAL      : A parameter is invalid.
    24172430 *  EWOULDBLOCK : The queue was empty.
    24182431 */
    2419 int fd_mq_tryget ( struct mqueue * queue, struct msg ** msg );
    2420 
    2421 /*
    2422  * FUNCTION:    fd_mq_timedget
    2423  *
    2424  * PARAMETERS:
    2425  *  queue       : The queue from which the message must be retrieved.
    2426  *  msg         : On return, the message is stored here.
    2427  *  abstime     : the absolute time until which we allow waiting for a message.
    2428  *
    2429  * DESCRIPTION:
    2430  *  This function is similar to fd_mq_get, except that it will block if the queue is empty
     2432int fd_fifo_tryget_int ( struct fifo * queue, void ** item );
     2433#define fd_fifo_tryget(queue, item) \
     2434        fd_fifo_tryget_int((queue), (void *)(item))
     2435
     2436/*
     2437 * FUNCTION:    fd_fifo_timedget
     2438 *
     2439 * PARAMETERS:
     2440 *  queue       : The queue from which the element must be retrieved.
     2441 *  item        : On return, the element is stored here.
     2442 *  abstime     : the absolute time until which we allow waiting for an item.
     2443 *
     2444 * DESCRIPTION:
     2445 *  This function is similar to fd_fifo_get, except that it will block if the queue is empty
    24312446 * only until the absolute time abstime (see pthread_cond_timedwait for + info).
    24322447 * If the queue is still empty when the time expires, the function returns ETIMEDOUT
    24332448 *
    24342449 * RETURN VALUE:
    2435  *  0           : A new message has been retrieved.
    2436  *  EINVAL      : A parameter is invalid.
    2437  *  ETIMEDOUT   : The time out has passed and no message has been received.
    2438  */
    2439 int fd_mq_timedget ( struct mqueue * queue, struct msg ** msg, const struct timespec *abstime );
     2450 *  0           : A new item has been retrieved.
     2451 *  EINVAL      : A parameter is invalid.
     2452 *  ETIMEDOUT   : The time out has passed and no item has been received.
     2453 */
     2454int fd_fifo_timedget_int ( struct fifo * queue, void ** item, const struct timespec *abstime );
     2455#define fd_fifo_timedget(queue, item, abstime) \
     2456        fd_fifo_timedget_int((queue), (void *)(item), (abstime))
    24402457
    24412458#endif /* _LIBFREEDIAMETER_H */
Note: See TracChangeset for help on using the changeset viewer.