📄 code_events.html
字号:
<html><title>Avida Events Implementation</title><body bgcolor="#FFFFFF" text="#000000" link="#0000AA" alink="#0000FF" vlink="#000044"><h2 align=center>Avida Events Implementation</h2><p>Events is one of the most complex sub-systems withinavida, but because of this we have automated the process of implementingnew events. Normally, when you want to add to acomponent of avida, you need to make changes in at least three places: theheader file to declare new classes or methods, the code file to writethe full definition of those methods, and a third location toactivate whatever you just wrote. A conscientious programmer will alsomake a fourth change to document this new feature.<p>Events used to be the worst case of this. Not only were more thanthese four procedures required, but they had to be done in a specificformat that even I would need to look up.<p>A few years ago Travis Collier wrote a program (in the language Perl) thatwould parse a single, specially-formatted file and write out the correspondingC++ code, including documentation. This program is"<tt><font color="#008844">current/source/event/</font><font color="#000088">make_events.pl</font></tt>",in case you are interested in it (fortunately, you don't need to understandit to add events because Perl code can be a bit dense).The file that the program reads in is"<tt><font color="#008844">current/source/event/</font><font color="#000088">cPopulation.events</font></tt>", which is what you will actually be editing.<p>When you type "<tt>make</tt>" to compile Avida, it will automatically lookto see if any modifications have been made to <tt>cPopulation.events</tt>,and if so it will run <tt>make_events.pl</tt> in order to update all ofthe event-related C++ files.<h3>The <tt><font color="#000088">cPopulation.events</font></tt> file</h3><p>This file defines all events currently in avida, most of which affect themain object from class cPopulation, hence the origin of the filename.There were once other event-definition files named for non-population objectsthat could be affected, but we collapsed it all down to this single file toavoid confusion. Ideally we'll change this file's name soon for furtherclarity.<p>The text in this file is broken up into blocks, separated by blank lines.Each block represents the full definition of a single event.Do <b>not</b> skip any lines when you are defining an event, or else thePerl script will think you have begun the definition of a new event.Below is the basic format for a single event. Anything in<font color="#886600">brown</font> should be changed to be event specific,while portions in black are the same for all events:<p><pre> <font color="#886600">event_name</font> :descr: /** * <font color="#886600">This is the documentation for this event. Notice that it can be</font> * <font color="#886600">multiple lines, but each line must begin with a single asterisk.</font> **/ :args: <font color="#886600">variable_type variable_name default_value</font> <font color="#886600">var2_type var2_name var2_default</font> <font color="#886600">... ... ...</font> <font color="#886600">varN_type varN_name varN_default</font> :body: <font color="#886600">FirstThingToDo();</font> <font color="#886600">ThenDoThis();</font> <font color="#886600">AndAnyOtherFunctionsToBeRun();</font></pre><p>For any event whose only function is to execute a method of the populationobject there really isn't much to write. All events have accessto <tt>population</tt>, which is a pointer to the primary population(of class cPopulation) in the Avida run. Additionally the events have accessto several static classes such as <tt>cAvidaDriver_Base</tt>, but since thisisn't something you've learned about yet, you shouldn't worry about it here.<p>Let's step through the sections of the event definition. First we have the<b><tt><font color="#886600">event_name</font></tt></b>, which can be anyalpha-numeric sequence plus the underscore. This name is the name that isused from the <tt>events.cfg</tt> configuration file to specify that this isthe event to be triggered.<p>The <b><tt>:descr:</tt></b> section is dropped as-is into the avida sourcecode as the comments for this event. In C++, two methods for includingcomments are possible. The first, is a pair of slashes('<b><tt>//</tt></b>') that make the remainder of the line a comment.The second is a slash-star ('<b><tt>/*</tt></b>') to begin a comment, andthen a star-slash ('<b><tt>*/</tt></b>') to denote its end. This latterapproach allows a command to go for multiple lines. To make it clear toa reader that this is all part of a single comment, good programmingpractice dictates that we should begin each line with a single star('<b><tt>*</tt></b>').In addition to being placed in the source code, this documentation isoutput when you run avida with the "<tt>-events</tt>" flag from the commandline. In the future, it will also be available from the graphical interface.<p>Next, we have the <b><tt>:args</tt></b> section of the event description.Here we list the variables that we want the user to set when they includethis event in their configuration. For example, if we create an event thatforces a single organism to write a term paper, we need to specify theorganism that will be subject to this unfortunate task. We might include aline in this section like "<tt>int cell_id</tt>". This would mean that whenthe user sets up this event, they <i>must</i> specify which cell they aretargeting. We could then include a second argument "<tt>int num_pages 5</tt>"so that the user can also specify how long the term paper should be. Butnotice that I included a "5" in this latter example. This means that theuser can include the second argument to specify the number of pages, but ifthey don't, 5 will be the default. Thus the event"<tt>write_term_paper 100 3</tt>" would make the organism in cell 100 write a three page term paper, while "<tt>write_term_paper 42</tt>" wouldmake the organism in cell 42 write a five page paper. Since we did notinclude a default argument for cell_id, that variable must always bespecified. Now, all you need to do is figure out how to best write thisevent, and you'll never have to write a paper again! Unfortunately, knowingthem, they would probably make huge margins and pad the paper with a bunchof <tt>nop-X</tt> commands, hoping we won't notice.<p>Finally, we come to the <b><tt>:body:</tt></b> section, which contains thecommands to be executed when this event is run. Since so much functionalityis already implemented in the cPopulation class, quite often all that weneed to do here is run a method of the population object. Below is such anexample, using the <tt>inject</tt> command.<h3>Example: The <tt>inject</tt> event</h3><p>The section headings are all <b>bold</b>; the remaining code usesa color scheme similar to the one I used previously:<center><table width=90%><tr><td width=50%><font color="#886600"><b>Comments</b> are BROWN</font><br> <font color="#008800">Names of <b>Methods</b> are GREEN</font><td width=50%><font color="#880000">Names of <b>types</b> (including <b>classes</b>) are RED</font><br> <font color="#000088"><b>Variable</b> names are BLUE</font></table></center><pre> <b>inject</b> <b>:descr:</b> <font color="#886600">/** * Injects a single organism into the population. * * Parameters: * filename (string) * The filename of the genotype to load. If this is left empty, or the keyword * "START_CREATURE" is given, than the genotype specified in the genesis * file under "START_CREATURE" is used. * cell ID (integer) default: 0 * The grid-point into which the organism should be placed.⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -