cruft/doc/tmpl/gras-unused.sgml

   1 <!-- ##### SECTION ./tmpl/DataDesc.sgml:Long_Description ##### -->
   2 <para>In order to allow GRAS to send data over the network (or simply to
   3 dupplicate it in SG), you have to describe the structure of data attached
   4 with each message. This mecanism is stolen from NWS message passing
   5 interface.</para>
   6
   7 <para>For each message, you have to declare a structure representing the
   8 data to send as payload with the message.</para>
   9
  10 <refsect2>
  11   <title>Sending (or receiving) simple structures</title>
  12   <para>Let's imagin you want to declare a <command>STORE_STATE</command>
  13   message, which will send some data to the memory server for inclusion in
  14   the database. Here is the structure we want to send:</para>
  15
  16 <literallayout>
  17  struct state {
  18   char id[STATE_NAME_SIZE];
  19   int rec_size;
  20   int rec_count;
  21   double seq_no;
  22   double time_out;
  23  };
  24 </literallayout>
  25
  26   <para>And here is the structure description GRAS needs to be able to send
  27   this over the network:</para>
  28
  29 <literallayout>
  30  const static DataDescriptor stateDescriptor[] =
  31   {SIMPLE_MEMBER(CHAR_TYPE, STATE_NAME_SIZE, offsetof(struct state, id)),
  32    SIMPLE_MEMBER(INT_TYPE, 1, offsetof(struct state, rec_size)),
  33    SIMPLE_MEMBER(INT_TYPE, 1, offsetof(struct state, rec_count)),
  34    SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(struct state, seq_no)),
  35    SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(struct state, time_out))};
  36 </literallayout>
  37
  38   <para>Contrary to what one could think when you first see it, it's pretty
  39   easy. A structure descriptor is a list of descriptions, describing each
  40   field of the structure. For example, for the first field, you say that
  41   the base type is <command>CHAR_TYPE</command>, that there is
  42   <command>STATE_NAME_SIZE</command> element of this type and that it's
  43   position in the structure is computed by <command>offsetof(struct state,
  44   id)</command>. This leads to two remarks:</para>
  45
  46   <itemizedlist>
  47     <listitem>
  48       <para>it's impossible to send dynamic sized strings that way. It's a
  49       known limitation, but I think we can live with it.</para>
  50     </listitem>
  51     <listitem>
  52       <para>Yes, the <command>offsetof(struct state, id)</command>
  53       construction is C ANSI and is portable.</para>
  54     </listitem>
  55   </itemizedlist>
  56 </refsect2>
  57
  58 <refsect2>
  59   <title>Sending (or receiving) complex structure</title>
  60   <para>How to send non-flat structures, do you ask? It's not harder. Let's
  61   imagin you want to send the following structure:</para>
  62
  63 <literallayout>
  64  typedef struct {
  65    unsigned long address;
  66    unsigned long port;
  67  } CliqueMember;
  68
  69  typedef struct {
  70    char name[MAX_CLIQUE_NAME_SIZE];
  71    double whenGenerated;
  72    double instance;
  73    char skill[MAX_SKILL_SIZE];
  74    char options[MAX_OPTIONS_SIZE];
  75    double period;
  76    double timeOut;
  77    CliqueMember members[MAX_MEMBERS];
  78    unsigned int count;
  79    unsigned int leader;
  80  } Clique;
  81 </literallayout>
  82
  83   <para>As you can see, this structure contains an array of another user
  84   defined structure. To be able to send <command>struct Clique</command>,
  85   you have to describe each structures that way:</para>
  86
  87 <literallayout>
  88  static const DataDescriptor cliqueMemberDescriptor[] =
  89    {SIMPLE_MEMBER(UNSIGNED_LONG_TYPE, 1, offsetof(CliqueMember, address)),
  90     SIMPLE_MEMBER(UNSIGNED_LONG_TYPE, 1, offsetof(CliqueMember, port))};
  91
  92  static const DataDescriptor cliqueDescriptor[] =
  93    {SIMPLE_MEMBER(CHAR_TYPE, MAX_CLIQUE_NAME_SIZE, offsetof(Clique, name)),
  94     SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, whenGenerated)),
  95     SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, instance)),
  96     SIMPLE_MEMBER(CHAR_TYPE, MAX_SKILL_SIZE, offsetof(Clique, skill)),
  97     SIMPLE_MEMBER(CHAR_TYPE, MAX_OPTIONS_SIZE, offsetof(Clique, options)),
  98     SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, period)),
  99     SIMPLE_MEMBER(DOUBLE_TYPE, 1, offsetof(Clique, timeOut)),
 100     {STRUCT_TYPE, MAX_MEMBERS, offsetof(Clique, members),
 101      (DataDescriptor *)&amp;cliqueMemberDescriptor, cliqueMemberDescriptorLength,
 102      PAD_BYTES(CliqueMember, port, unsigned long, 1)},
 103     SIMPLE_MEMBER(UNSIGNED_INT_TYPE, 1, offsetof(Clique, count)),
 104     SIMPLE_MEMBER(UNSIGNED_INT_TYPE, 1, offsetof(Clique, leader))};
 105 </literallayout>
 106
 107   <para>So, even if less natural, it is possible to send structures
 108   containing structures with these tools.</para>
 109
 110   <para>You can see that it's not only impossible to send dynamic-sized
 111   strings, it impossible to send dynamic-sized arrays. Here,
 112   <command>MAX_MEMBERS</command> is the maximum of members a clique can
 113   contain. In NWS, this value is defined to 100.  <warning><para>I'm not
 114   sure, but I think that all the 100 values are sent each time, even if
 115   there is only 3 non-null members. Yes, that's
 116   bad.</para></warning></para>
 117
 118   <warning><para>The DataDescriptor_t MUST be const. Malloc'ing them and
 119   then casting them on argument passing IS NOT OK. This is because we get
 120   the number of elements in the array with the sizeof(dd)/sizeof(dd[0]).
 121   </para></warning>
 122 </refsect2>
 123
 124
 125 <!-- ##### SECTION ./tmpl/DataDesc.sgml:See_Also ##### -->
 126 <para>
 127
 128 </para>
 129
 130
 131 <!-- ##### SECTION ./tmpl/DataDesc.sgml:Short_Description ##### -->
 132 Describing the data
 133
 134
 135 <!-- ##### SECTION ./tmpl/DataDesc.sgml:Title ##### -->
 136 DataDescriptor API
 137
 138
 139 <!-- ##### SECTION ./tmpl/ErrLog.sgml:Long_Description ##### -->
 140 <para>
 141
 142 </para>
 143
 144
 145 <!-- ##### SECTION ./tmpl/ErrLog.sgml:See_Also ##### -->
 146 <para>
 147
 148 </para>
 149
 150
 151 <!-- ##### SECTION ./tmpl/ErrLog.sgml:Short_Description ##### -->
 152
 153
 154
 155 <!-- ##### SECTION ./tmpl/ErrLog.sgml:Title ##### -->
 156 ErrLog
 157
 158
 159 <!-- ##### SECTION ./tmpl/Socks.sgml:Long_Description ##### -->
 160 <para>
 161
 162 </para>
 163
 164
 165 <!-- ##### SECTION ./tmpl/Socks.sgml:See_Also ##### -->
 166 <para>
 167
 168 </para>
 169
 170
 171 <!-- ##### SECTION ./tmpl/Socks.sgml:Short_Description ##### -->
 172 Handling sockets
 173
 174
 175 <!-- ##### SECTION ./tmpl/Socks.sgml:Title ##### -->
 176 Sockets API
 177
 178
 179 <!-- ##### SECTION ./tmpl/comm_dd_cbps.sgml:Long_Description ##### -->
 180 <para>
 181
 182 </para>
 183
 184
 185 <!-- ##### SECTION ./tmpl/comm_dd_cbps.sgml:See_Also ##### -->
 186 <para>
 187
 188 </para>
 189
 190
 191 <!-- ##### SECTION ./tmpl/comm_dd_cbps.sgml:Short_Description ##### -->
 192
 193
 194
 195 <!-- ##### SECTION ./tmpl/comm_dd_cbps.sgml:Title ##### -->
 196 Data description callbacks persistant state
 197
 198
 199 <!-- ##### SECTION ./tmpl/config.sgml:Long_Description ##### -->
 200 <para>
 201
 202 </para>
 203
 204
 205 <!-- ##### SECTION ./tmpl/config.sgml:See_Also ##### -->
 206 <para>
 207
 208 </para>
 209
 210
 211 <!-- ##### SECTION ./tmpl/config.sgml:Short_Description ##### -->
 212
 213
 214
 215 <!-- ##### SECTION ./tmpl/config.sgml:Title ##### -->
 216 config
 217
 218
 219 <!-- ##### SECTION ./tmpl/dd_cbps.sgml:Long_Description ##### -->
 220 <para>
 221
 222 </para>
 223
 224
 225 <!-- ##### SECTION ./tmpl/dd_cbps.sgml:See_Also ##### -->
 226 <para>
 227
 228 </para>
 229
 230
 231 <!-- ##### SECTION ./tmpl/dd_cbps.sgml:Short_Description ##### -->
 232
 233
 234
 235 <!-- ##### SECTION ./tmpl/dd_cbps.sgml:Title ##### -->
 236 Data description callbacks persistant state
 237
 238
 239 <!-- ##### SECTION ./tmpl/dico.sgml:Long_Description ##### -->
 240 <para>
 241
 242 </para>
 243
 244
 245 <!-- ##### SECTION ./tmpl/dico.sgml:See_Also ##### -->
 246 <para>
 247
 248 </para>
 249
 250
 251 <!-- ##### SECTION ./tmpl/dico.sgml:Short_Description ##### -->
 252
 253
 254
 255 <!-- ##### SECTION ./tmpl/dico.sgml:Title ##### -->
 256 dico
 257
 258
 259 <!-- ##### SECTION ./tmpl/dynar.sgml:Long_Description ##### -->
 260 <para>
 261 This module provide the quite usual dynamic array facility.
 262 </para>
 263
 264
 265 <!-- ##### SECTION ./tmpl/dynar.sgml:See_Also ##### -->
 266 <para>
 267
 268 </para>
 269
 270
 271 <!-- ##### SECTION ./tmpl/dynar.sgml:Short_Description ##### -->
 272 Dynamic array
 273
 274
 275 <!-- ##### SECTION ./tmpl/dynar.sgml:Title ##### -->
 276 dynar
 277
 278
 279 <!-- ##### SECTION ./tmpl/gras-overview.sgml:Long_Description ##### -->
 280     <para>This document introduce the GRAS library (<emphasis>Grid Reality
 281     And Simulation</emphasis>, or according to my english dictionary,
 282     <emphasis>Generally Recognized As Safe</emphasis> ;).</para>
 283
 284     <refsect2>
 285       <title>Overview</title>
 286       <para>The purpose of the GRAS is to allow the developpement of
 287       distributed programs which will work with as few as possible
 288       modification both on the SimGrid simulator (SG), and in the Real Life
 289       (RL).</para>
 290
 291       <para>Here are the problems when you want to do so:
 292         <itemizedlist>
 293           <listitem>
 294             <para>Communication in SG is done by passing tasks, while in
 295             RL, you have to deal with sockets (or any wrapper to it).</para>
 296           </listitem>
 297           <listitem><para>In RL, each process should provide a main()
 298             function, and it's obviously not the case in SG.</para>
 299           </listitem>
 300         </itemizedlist>
 301       </para>
 302     </refsect2>
 303     <refsect2>
 304       <title>Application class target</title>
 305       <para>If you want to run your code both in RL and in SG, you won't be
 306       able to use the full set of features offered by any of those two
 307       worlds. GRAS tries to provide a suffisent set of features to develop
 308       your application, and implement them in both worlds.</para>
 309
 310       <para>GRAS uses the paradigm of <emphasis>event-driven
 311       programming</emphasis>, which is an extension to the message-passing
 312       one. Any process of a typical event-driven application declares
 313       callback to incoming events, which can be messages from other
 314       processes, timers or others.</para>
 315
 316       <para>All messages have an header, specifying its type, and attached
 317       data, represented as one or several C structures. In order to send
 318       the data over the network in RL, a type-description mecanism is
 319       provided, and the RL version of GRAS implements CDR
 320       functionnalities. That is to say that the data are sent in the native
 321       format of the sender host, and converted on the destination host only
 322       if needed.</para>
 323
 324       <para>In order to not reimplement the wheel, GRAS use existing code,
 325       and adapt them to make them work together. The SG version naturally
 326       use the SimGrid toolkit, while the RL version is based over the
 327       communication library used in NWS (note that this library was somehow
 328       modified, since the previous version use XDR, ie both the sender and
 329       the receiver convert the data from/to a so called network
 330       format). That's why some basic knowledge about how NWS work is
 331       supposed in this document. But don't worry, you only have to know the
 332       basics about NWS, the internals needed to understand the document
 333       will be presented when needed.</para>
 334     </refsect2>
 335
 336
 337 <!-- ##### SECTION ./tmpl/gras-overview.sgml:See_Also ##### -->
 338 <para>
 339
 340 </para>
 341
 342
 343 <!-- ##### SECTION ./tmpl/gras-overview.sgml:Short_Description ##### -->
 344 Overview of the GRAS library
 345
 346
 347 <!-- ##### SECTION ./tmpl/gras-overview.sgml:Title ##### -->
 348 Overview
 349
 350
 351 <!-- ##### SECTION ./tmpl/gras.sgml:Long_Description ##### -->
 352 <para>
 353
 354 </para>
 355
 356
 357 <!-- ##### SECTION ./tmpl/gras.sgml:See_Also ##### -->
 358 <para>
 359
 360 </para>
 361
 362
 363 <!-- ##### SECTION ./tmpl/gras.sgml:Short_Description ##### -->
 364
 365
 366
 367 <!-- ##### SECTION ./tmpl/gras.sgml:Title ##### -->
 368 gras
 369
 370
 371 <!-- ##### SECTION ./tmpl/nws_comm.sgml:Long_Description ##### -->
 372 <para>
 373
 374 </para>
 375
 376
 377 <!-- ##### SECTION ./tmpl/nws_comm.sgml:See_Also ##### -->
 378 <para>
 379
 380 </para>
 381
 382
 383 <!-- ##### SECTION ./tmpl/nws_comm.sgml:Short_Description ##### -->
 384
 385
 386
 387 <!-- ##### SECTION ./tmpl/nws_comm.sgml:Title ##### -->
 388 nws_comm
 389
 390
 391 <!-- ##### SECTION ./tmpl/trp_socks.sgml:Long_Description ##### -->
 392 <para>
 393
 394 </para>
 395
 396
 397 <!-- ##### SECTION ./tmpl/trp_socks.sgml:See_Also ##### -->
 398 <para>
 399
 400 </para>
 401
 402
 403 <!-- ##### SECTION ./tmpl/trp_socks.sgml:Short_Description ##### -->
 404
 405
 406
 407 <!-- ##### SECTION ./tmpl/trp_socks.sgml:Title ##### -->
 408 Sockets
 409
 410
 411 <!-- ##### MACRO BEGIN_DECL ##### -->
 412 <para>
 413
 414 </para>
 415
 416
 417 <!-- ##### MACRO CCRITICAL0 ##### -->
 418 <para>
 419
 420 </para>
 421
 422 @c:
 423 @f:
 424
 425 <!-- ##### MACRO CCRITICAL1 ##### -->
 426 <para>
 427
 428 </para>
 429
 430 @c:
 431 @f:
 432 @a1:
 433
 434 <!-- ##### MACRO CCRITICAL2 ##### -->
 435 <para>
 436
 437 </para>
 438
 439 @c:
 440 @f:
 441 @a1:
 442 @a2:
 443
 444 <!-- ##### MACRO CCRITICAL3 ##### -->
 445 <para>
 446
 447 </para>
 448
 449 @c:
 450 @f:
 451 @a1:
 452 @a2:
 453 @a3:
 454
 455 <!-- ##### MACRO CCRITICAL4 ##### -->
 456 <para>
 457
 458 </para>
 459
 460 @c:
 461 @f:
 462 @a1:
 463 @a2:
 464 @a3:
 465 @a4:
 466
 467 <!-- ##### MACRO CCRITICAL5 ##### -->
 468 <para>
 469
 470 </para>
 471
 472 @c:
 473 @f:
 474 @a1:
 475 @a2:
 476 @a3:
 477 @a4:
 478 @a5:
 479
 480 <!-- ##### MACRO CDEBUG0 ##### -->
 481 <para>
 482
 483 </para>
 484
 485 @c:
 486 @f:
 487
 488 <!-- ##### MACRO CDEBUG1 ##### -->
 489 <para>
 490
 491 </para>
 492
 493 @c:
 494 @f:
 495 @a1:
 496
 497 <!-- ##### MACRO CDEBUG2 ##### -->
 498 <para>
 499
 500 </para>
 501
 502 @c:
 503 @f:
 504 @a1:
 505 @a2:
 506
 507 <!-- ##### MACRO CDEBUG3 ##### -->
 508 <para>
 509
 510 </para>
 511
 512 @c:
 513 @f:
 514 @a1:
 515 @a2:
 516 @a3:
 517
 518 <!-- ##### MACRO CDEBUG4 ##### -->
 519 <para>
 520
 521 </para>
 522
 523 @c:
 524 @f:
 525 @a1:
 526 @a2:
 527 @a3:
 528 @a4:
 529
 530 <!-- ##### MACRO CDEBUG5 ##### -->
 531 <para>
 532
 533 </para>
 534
 535 @c:
 536 @f:
 537 @a1:
 538 @a2:
 539 @a3:
 540 @a4:
 541 @a5:
 542
 543 <!-- ##### MACRO CERROR0 ##### -->
 544 <para>
 545
 546 </para>
 547
 548 @c:
 549 @f:
 550
 551 <!-- ##### MACRO CERROR1 ##### -->
 552 <para>
 553
 554 </para>
 555
 556 @c:
 557 @f:
 558 @a1:
 559
 560 <!-- ##### MACRO CERROR2 ##### -->
 561 <para>
 562
 563 </para>
 564
 565 @c:
 566 @f:
 567 @a1:
 568 @a2:
 569
 570 <!-- ##### MACRO CERROR3 ##### -->
 571 <para>
 572
 573 </para>
 574
 575 @c:
 576 @f:
 577 @a1:
 578 @a2:
 579 @a3:
 580
 581 <!-- ##### MACRO CERROR4 ##### -->
 582 <para>
 583
 584 </para>
 585
 586 @c:
 587 @f:
 588 @a1:
 589 @a2:
 590 @a3:
 591 @a4:
 592
 593 <!-- ##### MACRO CERROR5 ##### -->
 594 <para>
 595
 596 </para>
 597
 598 @c:
 599 @f:
 600 @a1:
 601 @a2:
 602 @a3:
 603 @a4:
 604 @a5:
 605
 606 <!-- ##### MACRO CINFO0 ##### -->
 607 <para>
 608
 609 </para>
 610
 611 @c:
 612 @f:
 613
 614 <!-- ##### MACRO CINFO1 ##### -->
 615 <para>
 616
 617 </para>
 618
 619 @c:
 620 @f:
 621 @a1:
 622
 623 <!-- ##### MACRO CINFO2 ##### -->
 624 <para>
 625
 626 </para>
 627
 628 @c:
 629 @f:
 630 @a1:
 631 @a2:
 632
 633 <!-- ##### MACRO CINFO3 ##### -->
 634 <para>
 635
 636 </para>
 637
 638 @c:
 639 @f:
 640 @a1:
 641 @a2:
 642 @a3:
 643
 644 <!-- ##### MACRO CINFO4 ##### -->
 645 <para>
 646
 647 </para>
 648
 649 @c:
 650 @f:
 651 @a1:
 652 @a2:
 653 @a3:
 654 @a4:
 655
 656 <!-- ##### MACRO CINFO5 ##### -->
 657 <para>
 658
 659 </para>
 660
 661 @c:
 662 @f:
 663 @a1:
 664 @a2:
 665 @a3:
 666 @a4:
 667 @a5:
 668
 669 <!-- ##### MACRO CLOG0 ##### -->
 670 <para>
 671
 672 </para>
 673
 674 @c:
 675 @p:
 676 @f:
 677
 678 <!-- ##### MACRO CLOG1 ##### -->
 679 <para>
 680
 681 </para>
 682
 683 @c:
 684 @p:
 685 @f:
 686 @a1:
 687
 688 <!-- ##### MACRO CLOG2 ##### -->
 689 <para>
 690
 691 </para>
 692
 693 @c:
 694 @p:
 695 @f:
 696 @a1:
 697 @a2:
 698
 699 <!-- ##### MACRO CLOG3 ##### -->
 700 <para>
 701
 702 </para>
 703
 704 @c:
 705 @p:
 706 @f:
 707 @a1:
 708 @a2:
 709 @a3:
 710
 711 <!-- ##### MACRO CLOG4 ##### -->
 712 <para>
 713
 714 </para>
 715
 716 @c:
 717 @p:
 718 @f:
 719 @a1:
 720 @a2:
 721 @a3:
 722 @a4:
 723
 724 <!-- ##### MACRO CLOG5 ##### -->
 725 <para>
 726
 727 </para>
 728
 729 @c:
 730 @p:
 731 @f:
 732 @a1:
 733 @a2:
 734 @a3:
 735 @a4:
 736 @a5:
 737
 738 <!-- ##### MACRO CLOG6 ##### -->
 739 <para>
 740
 741 </para>
 742
 743 @c:
 744 @p:
 745 @f:
 746 @a1:
 747 @a2:
 748 @a3:
 749 @a4:
 750 @a5:
 751 @a6:
 752
 753 <!-- ##### MACRO CRITICAL0 ##### -->
 754 <para>
 755
 756 </para>
 757
 758 @f:
 759
 760 <!-- ##### MACRO CRITICAL1 ##### -->
 761 <para>
 762
 763 </para>
 764
 765 @f:
 766 @a1:
 767
 768 <!-- ##### MACRO CRITICAL2 ##### -->
 769 <para>
 770
 771 </para>
 772
 773 @f:
 774 @a1:
 775 @a2:
 776
 777 <!-- ##### MACRO CRITICAL3 ##### -->
 778 <para>
 779
 780 </para>
 781
 782 @f:
 783 @a1:
 784 @a2:
 785 @a3:
 786
 787 <!-- ##### MACRO CRITICAL4 ##### -->
 788 <para>
 789
 790 </para>
 791
 792 @f:
 793 @a1:
 794 @a2:
 795 @a3:
 796 @a4:
 797
 798 <!-- ##### MACRO CRITICAL5 ##### -->
 799 <para>
 800
 801 </para>
 802
 803 @f:
 804 @a1:
 805 @a2:
 806 @a3:
 807 @a4:
 808 @a5:
 809
 810 <!-- ##### FUNCTION CallAddr ##### -->
 811 <para>
 812
 813 </para>
 814
 815 @addr:
 816 @Param2:
 817 @sock:
 818 @timeOut:
 819 @Returns:
 820
 821 <!-- ##### FUNCTION CloseSocket ##### -->
 822 <para>
 823
 824 </para>
 825
 826 @sock:
 827 @waitForPeer:
 828 @Returns:
 829
 830 <!-- ##### FUNCTION CreateLocalChild ##### -->
 831 <para>
 832
 833 </para>
 834
 835 @pid:
 836 @parentToChild:
 837 @childToParent:
 838 @Returns:
 839
 840 <!-- ##### FUNCTION DROP_SOCKET ##### -->
 841 <para>
 842
 843 </para>
 844
 845 @sock:
 846 @Returns:
 847
 848 <!-- ##### FUNCTION DataSize ##### -->
 849 <para>
 850
 851 </para>
 852
 853 @description:
 854 @length:
 855 @format:
 856 @Returns:
 857
 858 <!-- ##### ENUM DataTypes ##### -->
 859 <para>
 860
 861 </para>
 862
 863 @CHAR_TYPE:
 864 @DOUBLE_TYPE:
 865 @FLOAT_TYPE:
 866 @INT_TYPE:
 867 @LONG_TYPE:
 868 @SHORT_TYPE:
 869 @UNSIGNED_INT_TYPE:
 870 @UNSIGNED_LONG_TYPE:
 871 @UNSIGNED_SHORT_TYPE:
 872 @STRUCT_TYPE:
 873 @LAST_TYPE:
 874
 875 <!-- ##### MACRO END_DECL ##### -->
 876 <para>
 877
 878 </para>
 879
 880
 881 <!-- ##### MACRO EODD ##### -->
 882 <para>
 883
 884 </para>
 885
 886
 887 <!-- ##### FUNCTION EstablishAnEar ##### -->
 888 <para>
 889
 890 </para>
 891
 892 @Param1:
 893 @Param2:
 894 @ear:
 895 @earPort:
 896 @Returns:
 897
 898 <!-- ##### ENUM FormatTypes ##### -->
 899 <para>
 900
 901 </para>
 902
 903 @HOST_FORMAT:
 904 @NETWORK_FORMAT:
 905
 906 <!-- ##### MACRO GRAS_LOG_MAYDAY ##### -->
 907 <para>
 908
 909 </para>
 910
 911
 912 <!-- ##### MACRO GRAS_LOG_ROOT_CAT ##### -->
 913 <para>
 914
 915 </para>
 916
 917
 918 <!-- ##### MACRO HAVE_DLFCN_H ##### -->
 919 <para>
 920
 921 </para>
 922
 923
 924 <!-- ##### MACRO HAVE_INTTYPES_H ##### -->
 925 <para>
 926
 927 </para>
 928
 929
 930 <!-- ##### MACRO HAVE_LIBPTHREAD ##### -->
 931 <para>
 932
 933 </para>
 934
 935
 936 <!-- ##### MACRO HAVE_MEMORY_H ##### -->
 937 <para>
 938
 939 </para>
 940
 941
 942 <!-- ##### MACRO HAVE_STDINT_H ##### -->
 943 <para>
 944
 945 </para>
 946
 947
 948 <!-- ##### MACRO HAVE_STDLIB_H ##### -->
 949 <para>
 950
 951 </para>
 952
 953
 954 <!-- ##### MACRO HAVE_STRINGS_H ##### -->
 955 <para>
 956
 957 </para>
 958
 959
 960 <!-- ##### MACRO HAVE_STRING_H ##### -->
 961 <para>
 962
 963 </para>
 964
 965
 966 <!-- ##### MACRO HAVE_SYS_STAT_H ##### -->
 967 <para>
 968
 969 </para>
 970
 971
 972 <!-- ##### MACRO HAVE_SYS_TYPES_H ##### -->
 973 <para>
 974
 975 </para>
 976
 977
 978 <!-- ##### MACRO HAVE_UNISTD_H ##### -->
 979 <para>
 980
 981 </para>
 982
 983
 984 <!-- ##### TYPEDEF IPAddress ##### -->
 985 <para>
 986
 987 </para>
 988
 989
 990 <!-- ##### FUNCTION IPAddressImage ##### -->
 991 <para>
 992
 993 </para>
 994
 995 @addr:
 996 @Returns:
 997
 998 <!-- ##### FUNCTION IPAddressImage_r ##### -->
 999 <para>
1000
1001 </para>
1002
1003 @addr:
1004 @Returns:
1005
1006 <!-- ##### FUNCTION IPAddressMachine ##### -->
1007 <para>
1008
1009 </para>
1010
1011 @addr:
1012 @Returns:
1013
1014 <!-- ##### FUNCTION IPAddressMachine_r ##### -->
1015 <para>
1016
1017 </para>
1018
1019 @addr:
1020 @Returns:
1021
1022 <!-- ##### MACRO IPAddressValue ##### -->
1023 <para>
1024
1025 </para>
1026
1027 @machineOrAddress:
1028 @address:
1029
1030 <!-- ##### FUNCTION IPAddressValues ##### -->
1031 <para>
1032
1033 </para>
1034
1035 @machineOrAddress:
1036 @addressList:
1037 @atMost:
1038 @Returns:
1039
1040 <!-- ##### FUNCTION IncomingRequest ##### -->
1041 <para>
1042
1043 </para>
1044
1045 @timeOut:
1046 @sd:
1047 @ldap:
1048 @Returns:
1049
1050 <!-- ##### FUNCTION IsOkay ##### -->
1051 <para>
1052
1053 </para>
1054
1055 @sd:
1056 @Returns:
1057
1058 <!-- ##### FUNCTION IsPipe ##### -->
1059 <para>
1060
1061 </para>
1062
1063 @sd:
1064 @Returns:
1065
1066 <!-- ##### MACRO IsValidIP ##### -->
1067 <para>
1068
1069 </para>
1070
1071 @machineOrAddress:
1072
1073 <!-- ##### MACRO LOG6 ##### -->
1074 <para>
1075
1076 </para>
1077
1078 @p:
1079 @f:
1080 @a1:
1081 @a2:
1082 @a3:
1083 @a4:
1084 @a5:
1085 @a6:
1086
1087 <!-- ##### FUNCTION MyMachineName ##### -->
1088 <para>
1089
1090 </para>
1091
1092 @Returns:
1093
1094 <!-- ##### MACRO NO_SOCKET ##### -->
1095 <para>
1096
1097 </para>
1098
1099
1100 <!-- ##### FUNCTION NotifyOnDisconnection ##### -->
1101 <para>
1102
1103 </para>
1104
1105 @notifyFn:
1106
1107 <!-- ##### FUNCTION OpenClientSocket ##### -->
1108 <para>
1109
1110 </para>
1111
1112 @addr:
1113 @Param2:
1114 @sock:
1115 @Returns:
1116
1117 <!-- ##### FUNCTION OpenServerSocket ##### -->
1118 <para>
1119
1120 </para>
1121
1122 @Param1:
1123 @Param2:
1124 @ear:
1125 @earPort:
1126 @Returns:
1127
1128 <!-- ##### MACRO PACKAGE ##### -->
1129 <para>
1130
1131 </para>
1132
1133
1134 <!-- ##### MACRO PACKAGE_BUGREPORT ##### -->
1135 <para>
1136
1137 </para>
1138
1139
1140 <!-- ##### MACRO PACKAGE_NAME ##### -->
1141 <para>
1142
1143 </para>
1144
1145
1146 <!-- ##### MACRO PACKAGE_STRING ##### -->
1147 <para>
1148
1149 </para>
1150
1151
1152 <!-- ##### MACRO PACKAGE_TARNAME ##### -->
1153 <para>
1154
1155 </para>
1156
1157
1158 <!-- ##### MACRO PACKAGE_VERSION ##### -->
1159 <para>
1160
1161 </para>
1162
1163
1164 <!-- ##### MACRO PAD_BYTES ##### -->
1165 <para>
1166
1167 </para>
1168
1169 @structType:
1170 @lastMember:
1171 @memberType:
1172 @repetitions:
1173
1174 <!-- ##### FUNCTION PassSocket ##### -->
1175 <para>
1176
1177 </para>
1178
1179 @sock:
1180 @child:
1181 @Returns:
1182
1183 <!-- ##### FUNCTION Peer ##### -->
1184 <para>
1185
1186 </para>
1187
1188 @sd:
1189 @Returns:
1190
1191 <!-- ##### FUNCTION PeerName ##### -->
1192 <para>
1193
1194 </para>
1195
1196 @sd:
1197 @Returns:
1198
1199 <!-- ##### FUNCTION PeerName_r ##### -->
1200 <para>
1201
1202 </para>
1203
1204 @sd:
1205 @Returns:
1206
1207 <!-- ##### MACRO SIMPLE_DATA ##### -->
1208 <para>
1209
1210 </para>
1211
1212 @type:
1213 @repetitions:
1214
1215 <!-- ##### MACRO SIMPLE_MEMBER ##### -->
1216 <para>
1217
1218 </para>
1219
1220 @type:
1221 @repetitions:
1222 @offset:
1223
1224 <!-- ##### MACRO STDC_HEADERS ##### -->
1225 <para>
1226
1227 </para>
1228
1229
1230 <!-- ##### TYPEDEF Socket ##### -->
1231 <para>
1232
1233 </para>
1234
1235
1236 <!-- ##### FUNCTION SocketFailure ##### -->
1237 <para>
1238
1239 </para>
1240
1241 @sig:
1242
1243 <!-- ##### USER_FUNCTION SocketFunction ##### -->
1244 <para>
1245
1246 </para>
1247
1248 @Param1:
1249
1250 <!-- ##### FUNCTION SocketInUse ##### -->
1251 <para>
1252
1253 </para>
1254
1255 @sd:
1256 @Returns:
1257
1258 <!-- ##### FUNCTION SocketIsAvailable ##### -->
1259 <para>
1260
1261 </para>
1262
1263 @sd:
1264 @Returns:
1265
1266 <!-- ##### MACRO VERSION ##### -->
1267 <para>
1268
1269 </para>
1270
1271
1272 <!-- ##### USER_FUNCTION grasCallbackFunction ##### -->
1273 <para>
1274
1275 </para>
1276
1277 @sd:
1278 @msgType:
1279 @vdata:
1280
1281 <!-- ##### FUNCTION grasCloseSocket ##### -->
1282 <para>
1283
1284 </para>
1285
1286 @sock:
1287 @Returns:
1288
1289 <!-- ##### FUNCTION grasDataDescCmp ##### -->
1290 <para>
1291
1292 </para>
1293
1294 @dd1:
1295 @c1:
1296 @dd2:
1297 @c2:
1298 @Returns:
1299 @description:
1300
1301 <!-- ##### FUNCTION grasDataDescCount ##### -->
1302 <para>
1303
1304 </para>
1305
1306 @description:
1307 @Returns:
1308
1309 <!-- ##### FUNCTION grasDataRecv ##### -->
1310 <para>
1311
1312 </para>
1313
1314 @sd:
1315 @data:
1316 @description:
1317 @description_length:
1318 @repetition:
1319 @Returns:
1320
1321 <!-- ##### FUNCTION grasDataSend ##### -->
1322 <para>
1323
1324 </para>
1325
1326 @sd:
1327 @data:
1328 @description:
1329 @description_length:
1330 @repetition:
1331 @Returns:
1332
1333 <!-- ##### FUNCTION grasDataSize ##### -->
1334 <para>
1335
1336 </para>
1337
1338 @description:
1339 @ft:
1340 @Returns:
1341
1342 <!-- ##### ENUM grasError_t ##### -->
1343 <para>
1344
1345 </para>
1346
1347 @no_error:
1348 @malloc_error:
1349 @mismatch_error:
1350 @sanity_error:
1351 @system_error:
1352 @network_error:
1353 @timeout_error:
1354 @thread_error:
1355 @unknown_error:
1356
1357 <!-- ##### FUNCTION grasLock ##### -->
1358 <para>
1359
1360 </para>
1361
1362 @Returns:
1363
1364 <!-- ##### TYPEDEF grasMessageType_t ##### -->
1365 <para>
1366
1367 </para>
1368
1369
1370 <!-- ##### FUNCTION grasMsgDiscard ##### -->
1371 <para>
1372
1373 </para>
1374
1375 @sd:
1376 @size:
1377
1378 <!-- ##### FUNCTION grasMsgEntryGet ##### -->
1379 <para>
1380
1381 </para>
1382
1383 @id:
1384 @Returns:
1385
1386 <!-- ##### TYPEDEF grasMsgEntry_t ##### -->
1387 <para>
1388
1389 </para>
1390
1391
1392 <!-- ##### FUNCTION grasMsgFree ##### -->
1393 <para>
1394
1395 </para>
1396
1397 @msg:
1398
1399 <!-- ##### FUNCTION grasMsgHandle ##### -->
1400 <para>
1401
1402 </para>
1403
1404 @timeOut:
1405
1406 <!-- ##### FUNCTION grasMsgHeaderNew ##### -->
1407 <para>
1408
1409 </para>
1410
1411 @msgId:
1412 @dataSize:
1413 @seqCount:
1414 @Returns:
1415
1416 <!-- ##### FUNCTION grasMsgNew ##### -->
1417 <para>
1418
1419 </para>
1420
1421 @msgId:
1422 @free_data_on_free:
1423 @seqCount:
1424 @Varargs:
1425 @Returns:
1426
1427 <!-- ##### FUNCTION grasMsgRegister ##### -->
1428 <para>
1429
1430 </para>
1431
1432 @message:
1433 @name:
1434 @sequence_count:
1435 @Varargs:
1436 @Returns:
1437
1438 <!-- ##### FUNCTION grasMsgSend ##### -->
1439 <para>
1440
1441 </para>
1442
1443 @sd:
1444 @message:
1445 @sequence_count:
1446 @Varargs:
1447 @Returns:
1448
1449 <!-- ##### FUNCTION grasMsgWait ##### -->
1450 <para>
1451
1452 </para>
1453
1454 @sd:
1455 @timeout:
1456 @message:
1457 @sequence_count:
1458 @Varargs:
1459 @Returns:
1460
1461 <!-- ##### FUNCTION grasMyMachineName ##### -->
1462 <para>
1463
1464 </para>
1465
1466 @Returns:
1467
1468 <!-- ##### FUNCTION grasOpenClientSocket ##### -->
1469 <para>
1470
1471 </para>
1472
1473 @host:
1474 @Param2:
1475 @sock:
1476 @Returns:
1477
1478 <!-- ##### FUNCTION grasOpenServerSocket ##### -->
1479 <para>
1480
1481 </para>
1482
1483 @Param1:
1484 @Param2:
1485 @sock:
1486 @Returns:
1487
1488 <!-- ##### MACRO grasPROTOCOL ##### -->
1489 <para>
1490
1491 </para>
1492
1493
1494 <!-- ##### FUNCTION grasPeerGetAddress ##### -->
1495 <para>
1496
1497 </para>
1498
1499 @sd:
1500 @Returns:
1501
1502 <!-- ##### FUNCTION grasPeerGetName ##### -->
1503 <para>
1504
1505 </para>
1506
1507 @sd:
1508 @Returns:
1509
1510 <!-- ##### FUNCTION grasRecvData ##### -->
1511 <para>
1512
1513 </para>
1514
1515 @sd:
1516 @data:
1517 @description:
1518 @Returns:
1519
1520 <!-- ##### FUNCTION grasRegisterCallback ##### -->
1521 <para>
1522
1523 </para>
1524
1525 @message:
1526 @TTL:
1527 @cb:
1528
1529 <!-- ##### FUNCTION grasSendData ##### -->
1530 <para>
1531
1532 </para>
1533
1534 @sd:
1535 @data:
1536 @description:
1537 @Returns:
1538
1539 <!-- ##### FUNCTION grasUnlock ##### -->
1540 <para>
1541
1542 </para>
1543
1544 @Returns:
1545
1546 <!-- ##### FUNCTION grasUserdataGet ##### -->
1547 <para>
1548
1549 </para>
1550
1551
1552 <!-- ##### MACRO grasUserdataNew ##### -->
1553 <para>
1554
1555 </para>
1556
1557 @type:
1558
1559 <!-- ##### FUNCTION grasUserdataSet ##### -->
1560 <para>
1561
1562 </para>
1563
1564 @ud:
1565
1566 <!-- ##### FUNCTION gras_datadesc_cmp ##### -->
1567 <para>
1568
1569 </para>
1570
1571 @d1:
1572 @d2:
1573 @Returns:
1574 @dd1:
1575 @c1:
1576 @dd2:
1577 @c2:
1578
1579 <!-- ##### FUNCTION gras_datadesc_copy_data ##### -->
1580 <para>
1581
1582 </para>
1583
1584 @dd:
1585 @c:
1586 @data:
1587
1588 <!-- ##### FUNCTION gras_dict_cursor_next ##### -->
1589 <para>
1590
1591 </para>
1592
1593 @cursor:
1594 @Returns:
1595
1596 <!-- ##### FUNCTION gras_dynar_first ##### -->
1597 <para>
1598
1599 </para>
1600
1601 @dynar:
1602 @cursor:
1603 @Returns:
1604
1605 <!-- ##### FUNCTION gras_dynar_next ##### -->
1606 <para>
1607
1608 </para>
1609
1610 @dynar:
1611 @cursor:
1612 @whereto:
1613 @Returns:
1614
1615 <!-- ##### FUNCTION gras_lock ##### -->
1616 <para>
1617
1618 </para>
1619
1620 @Returns:
1621
1622 <!-- ##### FUNCTION gras_log_parent_set ##### -->
1623 <para>
1624
1625 </para>
1626
1627 @cat:
1628 @parent:
1629
1630 <!-- ##### FUNCTION gras_log_threshold_set ##### -->
1631 <para>
1632
1633 </para>
1634
1635 @cat:
1636 @thresholdPriority:
1637
1638 <!-- ##### FUNCTION gras_sock_client_open ##### -->
1639 <para>
1640
1641 </para>
1642
1643 @host:
1644 @Param2:
1645 @sock:
1646 @Returns:
1647
1648 <!-- ##### FUNCTION gras_sock_close ##### -->
1649 <para>
1650
1651 </para>
1652
1653 @sock:
1654 @Returns:
1655
1656 <!-- ##### FUNCTION gras_sock_get_peer_addr ##### -->
1657 <para>
1658
1659 </para>
1660
1661 @sd:
1662 @Returns:
1663
1664 <!-- ##### FUNCTION gras_sock_get_peer_name ##### -->
1665 <para>
1666
1667 </para>
1668
1669 @sd:
1670 @Returns:
1671
1672 <!-- ##### FUNCTION gras_sock_server_open ##### -->
1673 <para>
1674
1675 </para>
1676
1677 @Param1:
1678 @Param2:
1679 @sock:
1680 @Returns:
1681
1682 <!-- ##### FUNCTION gras_socket_peer_name ##### -->
1683 <para>
1684
1685 </para>
1686
1687 @sd:
1688 @Returns:
1689
1690 <!-- ##### FUNCTION gras_unlock ##### -->
1691 <para>
1692
1693 </para>
1694
1695 @Returns:
1696