Annotation of embedaddon/bird/doc/prog-8.html, revision 1.1
1.1 ! misho 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
! 2: <HTML>
! 3: <HEAD>
! 4: <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9">
! 5: <TITLE>BIRD Programmer's Documentation: Resources</TITLE>
! 6: <LINK HREF="prog-7.html" REL=previous>
! 7: <LINK HREF="prog.html#toc8" REL=contents>
! 8: </HEAD>
! 9: <BODY>
! 10: Next
! 11: <A HREF="prog-7.html">Previous</A>
! 12: <A HREF="prog.html#toc8">Contents</A>
! 13: <HR>
! 14: <H2><A NAME="s8">8.</A> <A HREF="prog.html#toc8">Resources</A></H2>
! 15:
! 16: <H2><A NAME="ss8.1">8.1</A> <A HREF="prog.html#toc8.1">Introduction</A>
! 17: </H2>
! 18:
! 19: <P>Most large software projects implemented in classical procedural
! 20: programming languages usually end up with lots of code taking care
! 21: of resource allocation and deallocation. Bugs in such code are often
! 22: very difficult to find, because they cause only `resource leakage',
! 23: that is keeping a lot of memory and other resources which nobody
! 24: references to.
! 25: <P>
! 26: <P>We've tried to solve this problem by employing a resource tracking
! 27: system which keeps track of all the resources allocated by all the
! 28: modules of BIRD, deallocates everything automatically when a module
! 29: shuts down and it is able to print out the list of resources and
! 30: the corresponding modules they are allocated by.
! 31: <P>
! 32: <P>Each allocated resource (from now we'll speak about allocated
! 33: resources only) is represented by a structure starting with a standard
! 34: header (struct <I>resource</I>) consisting of a list node (resources are
! 35: often linked to various lists) and a pointer to <I>resclass</I> -- a resource
! 36: class structure pointing to functions implementing generic resource
! 37: operations (such as freeing of the resource) for the particular resource
! 38: type.
! 39: <P>
! 40: <P>There exist the following types of resources:
! 41: <P>
! 42: <UL>
! 43: <LI><I>Resource pools</I> (<I>pool</I>)</LI>
! 44: <LI><I>Memory blocks</I></LI>
! 45: <LI><I>Linear memory pools</I> (<I>linpool</I>)</LI>
! 46: <LI><I>Slabs</I> (<I>slab</I>)</LI>
! 47: <LI><I>Events</I> (<I>event</I>) </LI>
! 48: <LI><I>Timers</I> (<I>timer</I>) </LI>
! 49: <LI><I>Sockets</I> (<I>socket</I>) </LI>
! 50: </UL>
! 51: <H2><A NAME="ss8.2">8.2</A> <A HREF="prog.html#toc8.2">Resource pools</A>
! 52: </H2>
! 53:
! 54: <P>
! 55: <P>Resource pools (<I>pool</I>) are just containers holding a list of
! 56: other resources. Freeing a pool causes all the listed resources
! 57: to be freed as well. Each existing <I>resource</I> is linked to some pool
! 58: except for a root pool which isn't linked anywhere, so all the
! 59: resources form a tree structure with internal nodes corresponding
! 60: to pools and leaves being the other resources.
! 61: <P>Example: Almost all modules of BIRD have their private pool which
! 62: is freed upon shutdown of the module.
! 63: <P>
! 64: <P><HR><H3>Function</H3>
! 65: <P><I>pool *</I>
! 66: <B>rp_new</B>
! 67: (<I>pool *</I> <B>p</B>, <I>char *</I> <B>name</B>) -- create a resource pool
! 68: <P>
! 69: <H3>Arguments</H3>
! 70: <P>
! 71: <DL>
! 72: <DT><I>pool *</I> <B>p</B><DD><P>parent pool
! 73: <DT><I>char *</I> <B>name</B><DD><P>pool name (to be included in debugging dumps)
! 74: </DL>
! 75: <H3>Description</H3>
! 76: <P><B>rp_new()</B> creates a new resource pool inside the specified
! 77: parent pool.
! 78:
! 79:
! 80: <HR><H3>Function</H3>
! 81: <P><I>void</I>
! 82: <B>rmove</B>
! 83: (<I>void *</I> <B>res</B>, <I>pool *</I> <B>p</B>) -- move a resource
! 84: <P>
! 85: <H3>Arguments</H3>
! 86: <P>
! 87: <DL>
! 88: <DT><I>void *</I> <B>res</B><DD><P>resource
! 89: <DT><I>pool *</I> <B>p</B><DD><P>pool to move the resource to
! 90: </DL>
! 91: <H3>Description</H3>
! 92: <P><B>rmove()</B> moves a resource from one pool to another.
! 93:
! 94:
! 95: <HR><H3>Function</H3>
! 96: <P><I>void</I>
! 97: <B>rfree</B>
! 98: (<I>void *</I> <B>res</B>) -- free a resource
! 99: <P>
! 100: <H3>Arguments</H3>
! 101: <P>
! 102: <DL>
! 103: <DT><I>void *</I> <B>res</B><DD><P>resource
! 104: </DL>
! 105: <H3>Description</H3>
! 106: <P><B>rfree()</B> frees the given resource and all information associated
! 107: with it. In case it's a resource pool, it also frees all the objects
! 108: living inside the pool.
! 109: <P>It works by calling a class-specific freeing function.
! 110:
! 111:
! 112: <HR><H3>Function</H3>
! 113: <P><I>void</I>
! 114: <B>rdump</B>
! 115: (<I>void *</I> <B>res</B>) -- dump a resource
! 116: <P>
! 117: <H3>Arguments</H3>
! 118: <P>
! 119: <DL>
! 120: <DT><I>void *</I> <B>res</B><DD><P>resource
! 121: </DL>
! 122: <H3>Description</H3>
! 123: <P>This function prints out all available information about the given
! 124: resource to the debugging output.
! 125: <P>It works by calling a class-specific dump function.
! 126:
! 127:
! 128: <HR><H3>Function</H3>
! 129: <P><I>void *</I>
! 130: <B>ralloc</B>
! 131: (<I>pool *</I> <B>p</B>, <I>struct resclass *</I> <B>c</B>) -- create a resource
! 132: <P>
! 133: <H3>Arguments</H3>
! 134: <P>
! 135: <DL>
! 136: <DT><I>pool *</I> <B>p</B><DD><P>pool to create the resource in
! 137: <DT><I>struct resclass *</I> <B>c</B><DD><P>class of the new resource
! 138: </DL>
! 139: <H3>Description</H3>
! 140: <P>This function is called by the resource classes to create a new
! 141: resource of the specified class and link it to the given pool.
! 142: Allocated memory is zeroed. Size of the resource structure is taken
! 143: from the <B>size</B> field of the <I>resclass</I>.
! 144:
! 145:
! 146: <HR><H3>Function</H3>
! 147: <P><I>void</I>
! 148: <B>rlookup</B>
! 149: (<I>unsigned long</I> <B>a</B>) -- look up a memory location
! 150: <P>
! 151: <H3>Arguments</H3>
! 152: <P>
! 153: <DL>
! 154: <DT><I>unsigned long</I> <B>a</B><DD><P>memory address
! 155: </DL>
! 156: <H3>Description</H3>
! 157: <P>This function examines all existing resources to see whether
! 158: the address <B>a</B> is inside any resource. It's used for debugging
! 159: purposes only.
! 160: <P>It works by calling a class-specific lookup function for each
! 161: resource.
! 162:
! 163:
! 164: <HR><H3>Function</H3>
! 165: <P><I>void</I>
! 166: <B>resource_init</B>
! 167: (<B>void</B>) -- initialize the resource manager
! 168: <P>
! 169: <H3>Description</H3>
! 170: <P>
! 171: <P>This function is called during BIRD startup. It initializes
! 172: all data structures of the resource manager and creates the
! 173: root pool.
! 174:
! 175: <H2><A NAME="ss8.3">8.3</A> <A HREF="prog.html#toc8.3">Memory blocks</A>
! 176: </H2>
! 177:
! 178: <P>
! 179: <P>Memory blocks are pieces of contiguous allocated memory.
! 180: They are a bit non-standard since they are represented not by a pointer
! 181: to <I>resource</I>, but by a void pointer to the start of data of the
! 182: memory block. All memory block functions know how to locate the header
! 183: given the data pointer.
! 184: <P>Example: All "unique" data structures such as hash tables are allocated
! 185: as memory blocks.
! 186: <P>
! 187: <P><HR><H3>Function</H3>
! 188: <P><I>void *</I>
! 189: <B>mb_alloc</B>
! 190: (<I>pool *</I> <B>p</B>, <I>unsigned</I> <B>size</B>) -- allocate a memory block
! 191: <P>
! 192: <H3>Arguments</H3>
! 193: <P>
! 194: <DL>
! 195: <DT><I>pool *</I> <B>p</B><DD><P>pool
! 196: <DT><I>unsigned</I> <B>size</B><DD><P>size of the block
! 197: </DL>
! 198: <H3>Description</H3>
! 199: <P><B>mb_alloc()</B> allocates memory of a given size and creates
! 200: a memory block resource representing this memory chunk
! 201: in the pool <B>p</B>.
! 202: <P>Please note that <B>mb_alloc()</B> returns a pointer to the memory
! 203: chunk, not to the resource, hence you have to free it using
! 204: <B>mb_free()</B>, not <B>rfree()</B>.
! 205:
! 206:
! 207: <HR><H3>Function</H3>
! 208: <P><I>void *</I>
! 209: <B>mb_allocz</B>
! 210: (<I>pool *</I> <B>p</B>, <I>unsigned</I> <B>size</B>) -- allocate and clear a memory block
! 211: <P>
! 212: <H3>Arguments</H3>
! 213: <P>
! 214: <DL>
! 215: <DT><I>pool *</I> <B>p</B><DD><P>pool
! 216: <DT><I>unsigned</I> <B>size</B><DD><P>size of the block
! 217: </DL>
! 218: <H3>Description</H3>
! 219: <P><B>mb_allocz()</B> allocates memory of a given size, initializes it to
! 220: zeroes and creates a memory block resource representing this memory
! 221: chunk in the pool <B>p</B>.
! 222: <P>Please note that <B>mb_allocz()</B> returns a pointer to the memory
! 223: chunk, not to the resource, hence you have to free it using
! 224: <B>mb_free()</B>, not <B>rfree()</B>.
! 225:
! 226:
! 227: <HR><H3>Function</H3>
! 228: <P><I>void *</I>
! 229: <B>mb_realloc</B>
! 230: (<I>void *</I> <B>m</B>, <I>unsigned</I> <B>size</B>) -- reallocate a memory block
! 231: <P>
! 232: <H3>Arguments</H3>
! 233: <P>
! 234: <DL>
! 235: <DT><I>void *</I> <B>m</B><DD><P>memory block
! 236: <DT><I>unsigned</I> <B>size</B><DD><P>new size of the block
! 237: </DL>
! 238: <H3>Description</H3>
! 239: <P><B>mb_realloc()</B> changes the size of the memory block <B>m</B> to a given size.
! 240: The contents will be unchanged to the minimum of the old and new sizes;
! 241: newly allocated memory will be uninitialized. Contrary to <B>realloc()</B>
! 242: behavior, <B>m</B> must be non-NULL, because the resource pool is inherited
! 243: from it.
! 244: <P>Like <B>mb_alloc()</B>, <B>mb_realloc()</B> also returns a pointer to the memory
! 245: chunk, not to the resource, hence you have to free it using
! 246: <B>mb_free()</B>, not <B>rfree()</B>.
! 247:
! 248:
! 249: <HR><H3>Function</H3>
! 250: <P><I>void</I>
! 251: <B>mb_free</B>
! 252: (<I>void *</I> <B>m</B>) -- free a memory block
! 253: <P>
! 254: <H3>Arguments</H3>
! 255: <P>
! 256: <DL>
! 257: <DT><I>void *</I> <B>m</B><DD><P>memory block
! 258: </DL>
! 259: <H3>Description</H3>
! 260: <P><B>mb_free()</B> frees all memory associated with the block <B>m</B>.
! 261:
! 262: <H2><A NAME="ss8.4">8.4</A> <A HREF="prog.html#toc8.4">Linear memory pools</A>
! 263: </H2>
! 264:
! 265: <P>
! 266: <P>Linear memory pools are collections of memory blocks which
! 267: support very fast allocation of new blocks, but are able to free only
! 268: the whole collection at once.
! 269: <P>Example: Each configuration is described by a complex system of structures,
! 270: linked lists and function trees which are all allocated from a single linear
! 271: pool, thus they can be freed at once when the configuration is no longer used.
! 272: <P>
! 273: <P><HR><H3>Function</H3>
! 274: <P><I>linpool *</I>
! 275: <B>lp_new</B>
! 276: (<I>pool *</I> <B>p</B>, <I>uint</I> <B>blk</B>) -- create a new linear memory pool
! 277: <P>
! 278: <H3>Arguments</H3>
! 279: <P>
! 280: <DL>
! 281: <DT><I>pool *</I> <B>p</B><DD><P>pool
! 282: <DT><I>uint</I> <B>blk</B><DD><P>block size
! 283: </DL>
! 284: <H3>Description</H3>
! 285: <P><B>lp_new()</B> creates a new linear memory pool resource inside the pool <B>p</B>.
! 286: The linear pool consists of a list of memory chunks of size at least
! 287: <B>blk</B>.
! 288:
! 289:
! 290: <HR><H3>Function</H3>
! 291: <P><I>void *</I>
! 292: <B>lp_alloc</B>
! 293: (<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) -- allocate memory from a <I>linpool</I>
! 294: <P>
! 295: <H3>Arguments</H3>
! 296: <P>
! 297: <DL>
! 298: <DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool
! 299: <DT><I>uint</I> <B>size</B><DD><P>amount of memory
! 300: </DL>
! 301: <H3>Description</H3>
! 302: <P><B>lp_alloc()</B> allocates <B>size</B> bytes of memory from a <I>linpool</I> <B>m</B>
! 303: and it returns a pointer to the allocated memory.
! 304: <P>It works by trying to find free space in the last memory chunk
! 305: associated with the <I>linpool</I> and creating a new chunk of the standard
! 306: size (as specified during <B>lp_new()</B>) if the free space is too small
! 307: to satisfy the allocation. If <B>size</B> is too large to fit in a standard
! 308: size chunk, an "overflow" chunk is created for it instead.
! 309:
! 310:
! 311: <HR><H3>Function</H3>
! 312: <P><I>void *</I>
! 313: <B>lp_allocu</B>
! 314: (<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) -- allocate unaligned memory from a <I>linpool</I>
! 315: <P>
! 316: <H3>Arguments</H3>
! 317: <P>
! 318: <DL>
! 319: <DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool
! 320: <DT><I>uint</I> <B>size</B><DD><P>amount of memory
! 321: </DL>
! 322: <H3>Description</H3>
! 323: <P><B>lp_allocu()</B> allocates <B>size</B> bytes of memory from a <I>linpool</I> <B>m</B>
! 324: and it returns a pointer to the allocated memory. It doesn't
! 325: attempt to align the memory block, giving a very efficient way
! 326: how to allocate strings without any space overhead.
! 327:
! 328:
! 329: <HR><H3>Function</H3>
! 330: <P><I>void *</I>
! 331: <B>lp_allocz</B>
! 332: (<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) -- allocate cleared memory from a <I>linpool</I>
! 333: <P>
! 334: <H3>Arguments</H3>
! 335: <P>
! 336: <DL>
! 337: <DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool
! 338: <DT><I>uint</I> <B>size</B><DD><P>amount of memory
! 339: </DL>
! 340: <H3>Description</H3>
! 341: <P>This function is identical to <B>lp_alloc()</B> except that it
! 342: clears the allocated memory block.
! 343:
! 344:
! 345: <HR><H3>Function</H3>
! 346: <P><I>void</I>
! 347: <B>lp_flush</B>
! 348: (<I>linpool *</I> <B>m</B>) -- flush a linear memory pool
! 349: <P>
! 350: <H3>Arguments</H3>
! 351: <P>
! 352: <DL>
! 353: <DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool
! 354: </DL>
! 355: <H3>Description</H3>
! 356: <P>This function frees the whole contents of the given <I>linpool</I> <B>m</B>,
! 357: but leaves the pool itself.
! 358:
! 359: <H2><A NAME="ss8.5">8.5</A> <A HREF="prog.html#toc8.5">Slabs</A>
! 360: </H2>
! 361:
! 362: <P>
! 363: <P>Slabs are collections of memory blocks of a fixed size.
! 364: They support very fast allocation and freeing of such blocks, prevent memory
! 365: fragmentation and optimize L2 cache usage. Slabs have been invented by Jeff Bonwick
! 366: and published in USENIX proceedings as `The Slab Allocator: An Object-Caching Kernel
! 367: Memory Allocator'. Our implementation follows this article except that we don't use
! 368: constructors and destructors.
! 369: <P>When the <CODE>DEBUGGING</CODE> switch is turned on, we automatically fill all
! 370: newly allocated and freed blocks with a special pattern to make detection
! 371: of use of uninitialized or already freed memory easier.
! 372: <P>Example: Nodes of a FIB are allocated from a per-FIB Slab.
! 373: <P>
! 374: <P><HR><H3>Function</H3>
! 375: <P><I>slab *</I>
! 376: <B>sl_new</B>
! 377: (<I>pool *</I> <B>p</B>, <I>uint</I> <B>size</B>) -- create a new Slab
! 378: <P>
! 379: <H3>Arguments</H3>
! 380: <P>
! 381: <DL>
! 382: <DT><I>pool *</I> <B>p</B><DD><P>resource pool
! 383: <DT><I>uint</I> <B>size</B><DD><P>block size
! 384: </DL>
! 385: <H3>Description</H3>
! 386: <P>This function creates a new Slab resource from which
! 387: objects of size <B>size</B> can be allocated.
! 388:
! 389:
! 390: <HR><H3>Function</H3>
! 391: <P><I>void *</I>
! 392: <B>sl_alloc</B>
! 393: (<I>slab *</I> <B>s</B>) -- allocate an object from Slab
! 394: <P>
! 395: <H3>Arguments</H3>
! 396: <P>
! 397: <DL>
! 398: <DT><I>slab *</I> <B>s</B><DD><P>slab
! 399: </DL>
! 400: <H3>Description</H3>
! 401: <P><B>sl_alloc()</B> allocates space for a single object from the
! 402: Slab and returns a pointer to the object.
! 403:
! 404:
! 405: <HR><H3>Function</H3>
! 406: <P><I>void</I>
! 407: <B>sl_free</B>
! 408: (<I>slab *</I> <B>s</B>, <I>void *</I> <B>oo</B>) -- return a free object back to a Slab
! 409: <P>
! 410: <H3>Arguments</H3>
! 411: <P>
! 412: <DL>
! 413: <DT><I>slab *</I> <B>s</B><DD><P>slab
! 414: <DT><I>void *</I> <B>oo</B><DD><P>object returned by <B>sl_alloc()</B>
! 415: </DL>
! 416: <H3>Description</H3>
! 417: <P>This function frees memory associated with the object <B>oo</B>
! 418: and returns it back to the Slab <B>s</B>.
! 419:
! 420: <H2><A NAME="ss8.6">8.6</A> <A HREF="prog.html#toc8.6">Events</A>
! 421: </H2>
! 422:
! 423: <P>
! 424: <P>Events are there to keep track of deferred execution.
! 425: Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller
! 426: parts, so that no module can monopolize the CPU. To split such a task, just create
! 427: an <I>event</I> resource, point it to the function you want to have called and call <B>ev_schedule()</B>
! 428: to ask the core to run the event when nothing more important requires attention.
! 429: <P>You can also define your own event lists (the <I>event_list</I> structure), enqueue your
! 430: events in them and explicitly ask to run them.
! 431: <P>
! 432: <P><HR><H3>Function</H3>
! 433: <P><I>event *</I>
! 434: <B>ev_new</B>
! 435: (<I>pool *</I> <B>p</B>) -- create a new event
! 436: <P>
! 437: <H3>Arguments</H3>
! 438: <P>
! 439: <DL>
! 440: <DT><I>pool *</I> <B>p</B><DD><P>resource pool
! 441: </DL>
! 442: <H3>Description</H3>
! 443: <P>This function creates a new event resource. To use it,
! 444: you need to fill the structure fields and call <B>ev_schedule()</B>.
! 445:
! 446:
! 447: <HR><H3>Function</H3>
! 448: <P><I>void</I>
! 449: <B>ev_run</B>
! 450: (<I>event *</I> <B>e</B>) -- run an event
! 451: <P>
! 452: <H3>Arguments</H3>
! 453: <P>
! 454: <DL>
! 455: <DT><I>event *</I> <B>e</B><DD><P>an event
! 456: </DL>
! 457: <H3>Description</H3>
! 458: <P>This function explicitly runs the event <B>e</B> (calls its hook
! 459: function) and removes it from an event list if it's linked to any.
! 460: <P>From the hook function, you can call <B>ev_enqueue()</B> or <B>ev_schedule()</B>
! 461: to re-add the event.
! 462:
! 463:
! 464: <HR><H3>Function</H3>
! 465: <P><I>void</I>
! 466: <B>ev_enqueue</B>
! 467: (<I>event_list *</I> <B>l</B>, <I>event *</I> <B>e</B>) -- enqueue an event
! 468: <P>
! 469: <H3>Arguments</H3>
! 470: <P>
! 471: <DL>
! 472: <DT><I>event_list *</I> <B>l</B><DD><P>an event list
! 473: <DT><I>event *</I> <B>e</B><DD><P>an event
! 474: </DL>
! 475: <H3>Description</H3>
! 476: <P><B>ev_enqueue()</B> stores the event <B>e</B> to the specified event
! 477: list <B>l</B> which can be run by calling <B>ev_run_list()</B>.
! 478:
! 479:
! 480: <HR><H3>Function</H3>
! 481: <P><I>void</I>
! 482: <B>ev_schedule</B>
! 483: (<I>event *</I> <B>e</B>) -- schedule an event
! 484: <P>
! 485: <H3>Arguments</H3>
! 486: <P>
! 487: <DL>
! 488: <DT><I>event *</I> <B>e</B><DD><P>an event
! 489: </DL>
! 490: <H3>Description</H3>
! 491: <P>This function schedules an event by enqueueing it to a system-wide
! 492: event list which is run by the platform dependent code whenever
! 493: appropriate.
! 494:
! 495:
! 496: <HR><H3>Function</H3>
! 497: <P><I>int</I>
! 498: <B>ev_run_list</B>
! 499: (<I>event_list *</I> <B>l</B>) -- run an event list
! 500: <P>
! 501: <H3>Arguments</H3>
! 502: <P>
! 503: <DL>
! 504: <DT><I>event_list *</I> <B>l</B><DD><P>an event list
! 505: </DL>
! 506: <H3>Description</H3>
! 507: <P>This function calls <B>ev_run()</B> for all events enqueued in the list <B>l</B>.
! 508:
! 509: <H2><A NAME="ss8.7">8.7</A> <A HREF="prog.html#toc8.7">Timers</A>
! 510: </H2>
! 511:
! 512: <P>
! 513: <P>Timers are resources which represent a wish of a module to call
! 514: a function at the specified time. The platform dependent code
! 515: doesn't guarantee exact timing, only that a timer function
! 516: won't be called before the requested time.
! 517: <P>In BIRD, time is represented by values of the <I>bird_clock_t</I> type
! 518: which are integral numbers interpreted as a relative number of seconds since
! 519: some fixed time point in past. The current time can be read
! 520: from variable <B>now</B> with reasonable accuracy and is monotonic. There is also
! 521: a current 'absolute' time in variable <B>now_real</B> reported by OS.
! 522: <P>Each timer is described by a <I>timer</I> structure containing a pointer
! 523: to the handler function (<B>hook</B>), data private to this function (<B>data</B>),
! 524: time the function should be called at (<B>expires</B>, 0 for inactive timers),
! 525: for the other fields see <CODE>timer.h</CODE>.
! 526: <P>
! 527: <P><HR><H3>Function</H3>
! 528: <P><I>timer *</I>
! 529: <B>tm_new</B>
! 530: (<I>pool *</I> <B>p</B>) -- create a timer
! 531: <P>
! 532: <H3>Arguments</H3>
! 533: <P>
! 534: <DL>
! 535: <DT><I>pool *</I> <B>p</B><DD><P>pool
! 536: </DL>
! 537: <H3>Description</H3>
! 538: <P>This function creates a new timer resource and returns
! 539: a pointer to it. To use the timer, you need to fill in
! 540: the structure fields and call <B>tm_start()</B> to start timing.
! 541:
! 542:
! 543: <HR><H3>Function</H3>
! 544: <P><I>void</I>
! 545: <B>tm_start</B>
! 546: (<I>timer *</I> <B>t</B>, <I>unsigned</I> <B>after</B>) -- start a timer
! 547: <P>
! 548: <H3>Arguments</H3>
! 549: <P>
! 550: <DL>
! 551: <DT><I>timer *</I> <B>t</B><DD><P>timer
! 552: <DT><I>unsigned</I> <B>after</B><DD><P>number of seconds the timer should be run after
! 553: </DL>
! 554: <H3>Description</H3>
! 555: <P>This function schedules the hook function of the timer to
! 556: be called after <B>after</B> seconds. If the timer has been already
! 557: started, it's <B>expire</B> time is replaced by the new value.
! 558: <P>You can have set the <B>randomize</B> field of <B>t</B>, the timeout
! 559: will be increased by a random number of seconds chosen
! 560: uniformly from range 0 .. <B>randomize</B>.
! 561: <P>You can call <B>tm_start()</B> from the handler function of the timer
! 562: to request another run of the timer. Also, you can set the <B>recurrent</B>
! 563: field to have the timer re-added automatically with the same timeout.
! 564:
! 565:
! 566: <HR><H3>Function</H3>
! 567: <P><I>void</I>
! 568: <B>tm_stop</B>
! 569: (<I>timer *</I> <B>t</B>) -- stop a timer
! 570: <P>
! 571: <H3>Arguments</H3>
! 572: <P>
! 573: <DL>
! 574: <DT><I>timer *</I> <B>t</B><DD><P>timer
! 575: </DL>
! 576: <H3>Description</H3>
! 577: <P>This function stops a timer. If the timer is already stopped,
! 578: nothing happens.
! 579:
! 580:
! 581: <HR><H3>Function</H3>
! 582: <P><I>bird_clock_t</I>
! 583: <B>tm_parse_datetime</B>
! 584: (<I>char *</I> <B>x</B>) -- parse a date and time
! 585: <P>
! 586: <H3>Arguments</H3>
! 587: <P>
! 588: <DL>
! 589: <DT><I>char *</I> <B>x</B><DD><P>datetime string
! 590: </DL>
! 591: <H3>Description</H3>
! 592: <P><B>tm_parse_datetime()</B> takes a textual representation of
! 593: a date and time (dd-mm-yyyy hh:mm:ss)
! 594: and converts it to the corresponding value of type <I>bird_clock_t</I>.
! 595:
! 596:
! 597: <HR><H3>Function</H3>
! 598: <P><I>bird_clock_t</I>
! 599: <B>tm_parse_date</B>
! 600: (<I>char *</I> <B>x</B>) -- parse a date
! 601: <P>
! 602: <H3>Arguments</H3>
! 603: <P>
! 604: <DL>
! 605: <DT><I>char *</I> <B>x</B><DD><P>date string
! 606: </DL>
! 607: <H3>Description</H3>
! 608: <P><B>tm_parse_date()</B> takes a textual representation of a date (dd-mm-yyyy)
! 609: and converts it to the corresponding value of type <I>bird_clock_t</I>.
! 610:
! 611:
! 612: <HR><H3>Function</H3>
! 613: <P><I>void</I>
! 614: <B>tm_format_datetime</B>
! 615: (<I>char *</I> <B>x</B>, <I>struct timeformat *</I> <B>fmt_spec</B>, <I>bird_clock_t</I> <B>t</B>) -- convert date and time to textual representation
! 616: <P>
! 617: <H3>Arguments</H3>
! 618: <P>
! 619: <DL>
! 620: <DT><I>char *</I> <B>x</B><DD><P>destination buffer of size <I>TM_DATETIME_BUFFER_SIZE</I>
! 621: <DT><I>struct timeformat *</I> <B>fmt_spec</B><DD><P>specification of resulting textual representation of the time
! 622: <DT><I>bird_clock_t</I> <B>t</B><DD><P>time
! 623: </DL>
! 624: <H3>Description</H3>
! 625: <P>This function formats the given relative time value <B>t</B> to a textual
! 626: date/time representation (dd-mm-yyyy hh:mm:ss) in real time.
! 627:
! 628: <H2><A NAME="ss8.8">8.8</A> <A HREF="prog.html#toc8.8">Sockets</A>
! 629: </H2>
! 630:
! 631: <P>
! 632: <P>Socket resources represent network connections. Their data structure (<I>socket</I>)
! 633: contains a lot of fields defining the exact type of the socket, the local and
! 634: remote addresses and ports, pointers to socket buffers and finally pointers to
! 635: hook functions to be called when new data have arrived to the receive buffer
! 636: (<B>rx_hook</B>), when the contents of the transmit buffer have been transmitted
! 637: (<B>tx_hook</B>) and when an error or connection close occurs (<B>err_hook</B>).
! 638: <P>Freeing of sockets from inside socket hooks is perfectly safe.
! 639: <P>
! 640: <P><HR><H3>Function</H3>
! 641: <P><I>int</I>
! 642: <B>sk_setup_multicast</B>
! 643: (<I>sock *</I> <B>s</B>) -- enable multicast for given socket
! 644: <P>
! 645: <H3>Arguments</H3>
! 646: <P>
! 647: <DL>
! 648: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 649: </DL>
! 650: <H3>Description</H3>
! 651: <P>Prepare transmission of multicast packets for given datagram socket.
! 652: The socket must have defined <B>iface</B>.
! 653: <H3>Result</H3>
! 654: <P>0 for success, -1 for an error.
! 655:
! 656:
! 657: <HR><H3>Function</H3>
! 658: <P><I>int</I>
! 659: <B>sk_join_group</B>
! 660: (<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>maddr</B>) -- join multicast group for given socket
! 661: <P>
! 662: <H3>Arguments</H3>
! 663: <P>
! 664: <DL>
! 665: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 666: <DT><I>ip_addr</I> <B>maddr</B><DD><P>multicast address
! 667: </DL>
! 668: <H3>Description</H3>
! 669: <P>Join multicast group for given datagram socket and associated interface.
! 670: The socket must have defined <B>iface</B>.
! 671: <H3>Result</H3>
! 672: <P>0 for success, -1 for an error.
! 673:
! 674:
! 675: <HR><H3>Function</H3>
! 676: <P><I>int</I>
! 677: <B>sk_leave_group</B>
! 678: (<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>maddr</B>) -- leave multicast group for given socket
! 679: <P>
! 680: <H3>Arguments</H3>
! 681: <P>
! 682: <DL>
! 683: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 684: <DT><I>ip_addr</I> <B>maddr</B><DD><P>multicast address
! 685: </DL>
! 686: <H3>Description</H3>
! 687: <P>Leave multicast group for given datagram socket and associated interface.
! 688: The socket must have defined <B>iface</B>.
! 689: <H3>Result</H3>
! 690: <P>0 for success, -1 for an error.
! 691:
! 692:
! 693: <HR><H3>Function</H3>
! 694: <P><I>int</I>
! 695: <B>sk_setup_broadcast</B>
! 696: (<I>sock *</I> <B>s</B>) -- enable broadcast for given socket
! 697: <P>
! 698: <H3>Arguments</H3>
! 699: <P>
! 700: <DL>
! 701: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 702: </DL>
! 703: <H3>Description</H3>
! 704: <P>Allow reception and transmission of broadcast packets for given datagram
! 705: socket. The socket must have defined <B>iface</B>. For transmission, packets should
! 706: be send to <B>brd</B> address of <B>iface</B>.
! 707: <H3>Result</H3>
! 708: <P>0 for success, -1 for an error.
! 709:
! 710:
! 711: <HR><H3>Function</H3>
! 712: <P><I>int</I>
! 713: <B>sk_set_ttl</B>
! 714: (<I>sock *</I> <B>s</B>, <I>int</I> <B>ttl</B>) -- set transmit TTL for given socket
! 715: <P>
! 716: <H3>Arguments</H3>
! 717: <P>
! 718: <DL>
! 719: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 720: <DT><I>int</I> <B>ttl</B><DD><P>TTL value
! 721: </DL>
! 722: <H3>Description</H3>
! 723: <P>Set TTL for already opened connections when TTL was not set before. Useful
! 724: for accepted connections when different ones should have different TTL.
! 725: <H3>Result</H3>
! 726: <P>0 for success, -1 for an error.
! 727:
! 728:
! 729: <HR><H3>Function</H3>
! 730: <P><I>int</I>
! 731: <B>sk_set_min_ttl</B>
! 732: (<I>sock *</I> <B>s</B>, <I>int</I> <B>ttl</B>) -- set minimal accepted TTL for given socket
! 733: <P>
! 734: <H3>Arguments</H3>
! 735: <P>
! 736: <DL>
! 737: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 738: <DT><I>int</I> <B>ttl</B><DD><P>TTL value
! 739: </DL>
! 740: <H3>Description</H3>
! 741: <P>Set minimal accepted TTL for given socket. Can be used for TTL security.
! 742: implementations.
! 743: <H3>Result</H3>
! 744: <P>0 for success, -1 for an error.
! 745:
! 746:
! 747: <HR><H3>Function</H3>
! 748: <P><I>int</I>
! 749: <B>sk_set_md5_auth</B>
! 750: (<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>local</B>, <I>ip_addr</I> <B>remote</B>, <I>struct iface *</I> <B>ifa</B>, <I>char *</I> <B>passwd</B>, <I>int</I> <B>setkey</B>) -- add / remove MD5 security association for given socket
! 751: <P>
! 752: <H3>Arguments</H3>
! 753: <P>
! 754: <DL>
! 755: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 756: <DT><I>ip_addr</I> <B>local</B><DD><P>IP address of local side
! 757: <DT><I>ip_addr</I> <B>remote</B><DD><P>IP address of remote side
! 758: <DT><I>struct iface *</I> <B>ifa</B><DD><P>Interface for link-local IP address
! 759: <DT><I>char *</I> <B>passwd</B><DD><P>Password used for MD5 authentication
! 760: <DT><I>int</I> <B>setkey</B><DD><P>Update also system SA/SP database
! 761: </DL>
! 762: <H3>Description</H3>
! 763: <P>In TCP MD5 handling code in kernel, there is a set of security associations
! 764: used for choosing password and other authentication parameters according to
! 765: the local and remote address. This function is useful for listening socket,
! 766: for active sockets it may be enough to set s->password field.
! 767: <P>When called with passwd != NULL, the new pair is added,
! 768: When called with passwd == NULL, the existing pair is removed.
! 769: <P>Note that while in Linux, the MD5 SAs are specific to socket, in BSD they are
! 770: stored in global SA/SP database (but the behavior also must be enabled on
! 771: per-socket basis). In case of multiple sockets to the same neighbor, the
! 772: socket-specific state must be configured for each socket while global state
! 773: just once per src-dst pair. The <B>setkey</B> argument controls whether the global
! 774: state (SA/SP database) is also updated.
! 775: <H3>Result</H3>
! 776: <P>0 for success, -1 for an error.
! 777:
! 778:
! 779: <HR><H3>Function</H3>
! 780: <P><I>int</I>
! 781: <B>sk_set_ipv6_checksum</B>
! 782: (<I>sock *</I> <B>s</B>, <I>int</I> <B>offset</B>) -- specify IPv6 checksum offset for given socket
! 783: <P>
! 784: <H3>Arguments</H3>
! 785: <P>
! 786: <DL>
! 787: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 788: <DT><I>int</I> <B>offset</B><DD><P>offset
! 789: </DL>
! 790: <H3>Description</H3>
! 791: <P>Specify IPv6 checksum field offset for given raw IPv6 socket. After that, the
! 792: kernel will automatically fill it for outgoing packets and check it for
! 793: incoming packets. Should not be used on ICMPv6 sockets, where the position is
! 794: known to the kernel.
! 795: <H3>Result</H3>
! 796: <P>0 for success, -1 for an error.
! 797:
! 798:
! 799: <HR><H3>Function</H3>
! 800: <P><I>sock *</I>
! 801: <B>sock_new</B>
! 802: (<I>pool *</I> <B>p</B>) -- create a socket
! 803: <P>
! 804: <H3>Arguments</H3>
! 805: <P>
! 806: <DL>
! 807: <DT><I>pool *</I> <B>p</B><DD><P>pool
! 808: </DL>
! 809: <H3>Description</H3>
! 810: <P>This function creates a new socket resource. If you want to use it,
! 811: you need to fill in all the required fields of the structure and
! 812: call <B>sk_open()</B> to do the actual opening of the socket.
! 813: <P>The real function name is <B>sock_new()</B>, <B>sk_new()</B> is a macro wrapper
! 814: to avoid collision with OpenSSL.
! 815:
! 816:
! 817: <HR><H3>Function</H3>
! 818: <P><I>int</I>
! 819: <B>sk_open</B>
! 820: (<I>sock *</I> <B>s</B>) -- open a socket
! 821: <P>
! 822: <H3>Arguments</H3>
! 823: <P>
! 824: <DL>
! 825: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 826: </DL>
! 827: <H3>Description</H3>
! 828: <P>This function takes a socket resource created by <B>sk_new()</B> and
! 829: initialized by the user and binds a corresponding network connection
! 830: to it.
! 831: <H3>Result</H3>
! 832: <P>0 for success, -1 for an error.
! 833:
! 834:
! 835: <HR><H3>Function</H3>
! 836: <P><I>int</I>
! 837: <B>sk_send</B>
! 838: (<I>sock *</I> <B>s</B>, <I>unsigned</I> <B>len</B>) -- send data to a socket
! 839: <P>
! 840: <H3>Arguments</H3>
! 841: <P>
! 842: <DL>
! 843: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 844: <DT><I>unsigned</I> <B>len</B><DD><P>number of bytes to send
! 845: </DL>
! 846: <H3>Description</H3>
! 847: <P>This function sends <B>len</B> bytes of data prepared in the
! 848: transmit buffer of the socket <B>s</B> to the network connection.
! 849: If the packet can be sent immediately, it does so and returns
! 850: 1, else it queues the packet for later processing, returns 0
! 851: and calls the <B>tx_hook</B> of the socket when the tranmission
! 852: takes place.
! 853:
! 854:
! 855: <HR><H3>Function</H3>
! 856: <P><I>int</I>
! 857: <B>sk_send_to</B>
! 858: (<I>sock *</I> <B>s</B>, <I>unsigned</I> <B>len</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>port</B>) -- send data to a specific destination
! 859: <P>
! 860: <H3>Arguments</H3>
! 861: <P>
! 862: <DL>
! 863: <DT><I>sock *</I> <B>s</B><DD><P>socket
! 864: <DT><I>unsigned</I> <B>len</B><DD><P>number of bytes to send
! 865: <DT><I>ip_addr</I> <B>addr</B><DD><P>IP address to send the packet to
! 866: <DT><I>unsigned</I> <B>port</B><DD><P>port to send the packet to
! 867: </DL>
! 868: <H3>Description</H3>
! 869: <P>This is a <B>sk_send()</B> replacement for connection-less packet sockets
! 870: which allows destination of the packet to be chosen dynamically.
! 871: Raw IP sockets should use 0 for <B>port</B>.
! 872:
! 873:
! 874: <HR><H3>Function</H3>
! 875: <P><I>void</I>
! 876: <B>io_log_event</B>
! 877: (<I>void *</I> <B>hook</B>, <I>void *</I> <B>data</B>) -- mark approaching event into event log
! 878: <P>
! 879: <H3>Arguments</H3>
! 880: <P>
! 881: <DL>
! 882: <DT><I>void *</I> <B>hook</B><DD><P>event hook address
! 883: <DT><I>void *</I> <B>data</B><DD><P>event data address
! 884: </DL>
! 885: <H3>Description</H3>
! 886: <P>Store info (hook, data, timestamp) about the following internal event into
! 887: a circular event log (<B>event_log</B>). When latency tracking is enabled, the log
! 888: entry is kept open (in <B>event_open</B>) so the duration can be filled later.
! 889:
! 890: <P>
! 891: <HR>
! 892: Next
! 893: <A HREF="prog-7.html">Previous</A>
! 894: <A HREF="prog.html#toc8">Contents</A>
! 895: </BODY>
! 896: </HTML>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to prog-8.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc