shotgun/lib/sendsite.h

   1 #ifndef RBX_SENDSITE_H
   2 #define RBX_SENDSITE_H
   3
   4
   5 typedef struct send_site _send_site;
   6
   7 typedef void (*send_site_lookup)(struct message *msg);
   8
   9 /*
  10
  11  Send sites is the core of method dispatch caching used by Rubinius.
  12  It is half C, half Ruby implementation. It is created for every message
  13  send site (or, for those coming from Java world, method call site) to
  14  store information about receiver and method responding to message
  15  sent. This information later help use cached compiled method if the method
  16  receiver handles message with has already been executed at this send site.
  17
  18  Selector is an object that represents a message (method name) and collection
  19  of references to every send site that uses the same message. Selectors are
  20  not used in method dispatch process though: they provide a reverse lookup
  21  of send sites for given method name.
  22
  23  You can pass -ps and -pss flags to Rubinius on launch and summary of most
  24  frequently encountered selectors and send sites will be printed on exit
  25  (so they stand for "print selectors" and "print send sites").
  26  Note that it summarizes most often send messages (method names), not actual methods
  27  executed, because many methods may have the same name in different classes or
  28  modules.
  29
  30  Note that OBJECT fields must be located at the start of the SendSite.
  31
  32
  33  == References
  34
  35  Send sites are also known as call sites in a variery of literature and on
  36  Wikipedia:
  37  http://tinyurl.com/22jpuy
  38
  39  Adam Gardiner wrote a great post on send sites in Rubinius:
  40  http://tinyurl.com/34c6e8
  41
  42
  43  == Structure fields
  44
  45  name     : the name of the message (i.e. method) this send site sends (calls)
  46  sender   : reference to the CompiledMethod in which the SendSite is located
  47  selector : a reference to the Selector instance corresponding to the message name
  48  data1    : class of the receiver
  49  data2    : The CompiledMethod corresponding to this message on the receiver class,
  50             as encountered on the last dispatch. When a message is dispatched,
  51             this is the target object that needs to be located; it contains the
  52             bytecode for the method on the receiver.
  53  data3    : the module
  54  data4    : the primitive index if the SendSite resolves to a primitive method
  55  hits     : counter of successfull caches of the receiver method
  56  misses   : counter of unsuccessful caches, respectively
  57  lookup   : pointer to function that performs actual method lookup
  58  c_data   : for an FFI send site, holds the address of the FFI stub function to call.
  59             for a primitive send site, holds the address of the primitive function
  60             to call.
  61 */
  62 struct send_site {
  63   OBJECT name;
  64   OBJECT sender;
  65   OBJECT selector;
  66   OBJECT data1;
  67   OBJECT data2;
  68   OBJECT data3;
  69
  70   int data4;
  71   int hits, misses;
  72   send_site_lookup lookup;
  73   void *c_data;
  74 };
  75
  76
  77 #define SENDSITE(obj) ((struct send_site*)BYTES_OF(obj))
  78
  79 #define SEND_SITE_OBJECT_FIELDS 6
  80
  81 void send_site_init(STATE);
  82 OBJECT send_site_create(STATE, OBJECT name);
  83 void send_site_set_sender(STATE, OBJECT self, OBJECT cm);
  84
  85 #endif