÷ƒ’À;è TeX output 1998.01.28:1944‹ÿÿÿÿ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIyóÓßŒ˜¼j ptmb7t½Index–/of“Swarm“documentation“(1.0.5)ŽŸìíïhtml:ï html:Ÿ Hƒóßêï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:©ÄI‘0óßêï html:still“not“available,“thisŽ¡‘0list–?ýof“resources“should“give“you“a“good“place“to“start.‘ úPlease“direct“all“questionsŽ¡‘0to–?ýthe“official“Swarm“mailing“list:‘ úïhtml:ï html:

ïhtml:ï html:Ž¦‘0(mailto:majordomo@santafe.edu)Ž¦‘0.Žïhtml:ï html:Ÿ‘0„¤ŽŽŸ¼jïhtml:ï html:Ÿ¦U½T‘þªable–/Of“Contents:ŽŸÃjïhtml:ï html:¤ïhtml:ï html:Ÿr‘0ïcolor push Black¿1.ï color popŽŽ‘<ïhtml:ï html:Introductionïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black2.ï color popŽŽ‘<ïhtml:ï html:Installationïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black3.ï color popŽŽŽŸ)Â’øqï>PSfile="eps/bomb.eps" llx=290 lly=365 urx=321 ury=396 rwi=310 ŽŽŸ ïhtml:ï html:¦‘0Compatibility–?ý--“ïhtml:ï html:READ“ME!!!ïhtml:ï html:ŽŸ8äïhtml:ï html:¤ ‹e‘0ïcolor push Black4.ï color popŽŽ‘<ïhtml:ï html:Objective-C‘?ýResourcesïhtml:ï html:ŽŸ8äïhtml:ï html:¡‘0ïcolor push Black5.ï color popŽŽ‘<ïhtml:ï html:Core‘?ýLibrariesïhtml:ï html:ŽŸïhtml:ï html:¦‘0ïcolor push Black6.ï color popŽŽ‘<ïhtml:ï html:User–?ýContributed“Librariesïhtml:ï html:Ž¦‘0(http://www.santafe.edu/projects/swarm/users/user-community.html)ŽŸ8äïhtml:ï html:¡‘0ïcolor push Black7.ï color popŽŽ‘<ïhtml:ï html:Sample‘?ýApplicationsïhtml:ï html:ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ€³óÓßŒ˜G® ptmb7tÀIntr°goductionŽŸ"~ó3{Ù ptmr7t¼Our–´home“page“proÙ vides“a“good“introduction“to“Swægarm“(what“it“does“and“what“it“aims“to“be).‘µÚOn“the“other“hand,‘ÁtheŽ¤apps-intro–üSdocument“aims“to“giÀvšÙ e“you“a“more“detailed“o˜v˜ervieÀw“of“the“sorts“of“things“a“user“needs“to“do“in“order“toŽ¡get–za“simulation“up“and“running“in“Swšægarm.‘˜The“combination“of“these“tw˜o“documents“should“help“you“decide“whetherŽ¡Sw•ægarm›€w“ould˜be˜a˜useful˜tool˜in˜the˜conteÙ xt˜of˜your˜research.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹* “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿ ‘:¿http://www.santafe.edu/projects/swarm/ïhtml:ï html:Ž©‘:(http://www.santafe.edu/projects/swarm/)ŽŸ8äïhtml:ï html:¤ á¬‘XSwarm's–?ýInternet“presence.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:intro.htmlïhtml:ï html:Ž¦‘:(intro.html)ŽŸÕSïhtml:ï html:ŸE=‘XWhat–?ýa“Swarm“application“looks“like,“and“how“it“is“developed.ŽŸ€’ïhtml:ï html:ŸžÀInstalling‘QëSwarmŽŸxÅ¼Swægarm–¯/uses“quite“a“feÀw“libraries“and“is“intended“to“run“under“all“major“ a•ÌÐv“ors–¯/of“Unix.‘§%This“presents“the“unpleasantŽ¤bšÌÐut–ïælarÑðgely“una˜v˜oidable“side-eect“of“making“Swægarm“hard“to“install.‘iKIdeally‘ÿY ,‘àyou“should“get“the“sys-admin“for“yourŽ¡site–€to“do“the“job™Ÿ.‘˜In“anšÙ y“eÀv˜ent,“the“folloÀwing“resources“should“pro˜v˜e“useful:ŽŸˆmïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿ ðX‘:¿http://www.santafe.edu/projects/swarm/release.htmlïhtml:ï html:Ž¦‘:(http://www.santafe.edu/projects/swarm/release.html)ŽŸ8äïhtml:ï html:¤ á¬‘XSwarm–?ýrelease“web“pages.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:install.htmlïhtml:ï html:Ž¦‘:(install.html)Ž¤ÕSïhtml:ï html:ŸE=‘XInstallation‘?ýinstructionsŽŸïhtml:ï html:ïhtml:ï html:¦‘:overview.htmlïhtml:ï html:Ž¦‘:(overview.html)Ž¡ïhtml:ï html:ŸE=‘XOverview–?ýof“the“Swarm“system.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ á¬‘:To–?ýDo“listïhtml:ï html:Ž¦‘:(todo.html)Ž¡ïhtml:ï html:ŸE=‘XAdditions–?ýwe“want“to“have“to“Swarm.ŽŸïhtml:ï html:ïhtml:ï html:¦‘:FAQ.htmlïhtml:ï html:Ž¦‘:(faq/FAQ.html)ŽŸ8äïhtml:ï html:¤ á¬‘XFAQ–?ýfor“the“Swarm“project.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:LICENSE-libsïhtml:ï html:Ž¦‘:(LICENSE-libs)ŽŸÕSïhtml:ï html:ŸE=‘XLicense–?ýterms“for“the“distribution“of“the“Swarm“libraries.ŽŸïhtml:ï html:ïhtml:ï html:¦‘:LICENSE-appsïhtml:ï html:Ž¦‘:(LICENSE-apps)ŽŸ8äïhtml:ï html:¡‘XLicense–?ýterms“for“this“distribution“of“the“Swarm“example“applications.ŽŸ€’ïhtml:ï html:Ÿ)Â’Úqï>PSfile="eps/bomb.eps" llx=290 lly=365 urx=321 ury=396 rwi=310 ŽŽŸÖúÀCompatibilityŽŸ âcïhtml:ï html:Ÿïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹? “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâïcolor push Black¿1.ï color popŽŽ‘;ºâ1.0.4–?ý=>“1.0.5Žºâ¤ïhtml:ï html:¡ïhtml:ï html:Ÿà‘<ïcolor push Blackó\ùð pzdrÁlï color popŽŽ‘F¿EZGraph's–?ýsetGraphWindowGeometryRecordName“and“GUISwarm's“setControlPanelGeometryRecordNameŽ¤‘Fhave–?ýbeen“retired.‘ úThe“macro“SET_WINDOW_GEOMETRY_RECORD_NAME“can“now“be“usedŽ¡‘Fin–?ýany“geometry“archiving“context.ŽŸ8äïhtml:ï html:© §‘<ïcolor push BlackÁlï color popŽŽ‘F¿After–?ýadjusting“an“application“per“previous“item,“be“aware“that“the“new“internalŽ¡‘Fnaming–?ýconventions“used“by“`GUIComposite'“classes“(e.g.‘ úEZBin“and“GUISwarm)Ž¡‘Fwill–?ýprobably“differ“from“the“archiving“keys“in“your“application.‘ úSuch“widgetsŽ¡‘Fwill–?ýprobably“lose“their“saved“placements.ŽŸ8äïhtml:ï html:¦‘0ïcolor push Black2.ï color popŽŽ‘<1.0.3–?ý=>“1.0.4Ž¤ïhtml:ï html:¡ïhtml:ï html:Ÿà‘<ïcolor push BlackÁlï color popŽŽ‘F¿doTkEvents–?ýhas“been“moved“from“ControlPanel“to“ActionCache.‘ úBe“sure“to“directŽ¤‘Fall–?ýdoTkEvent“messages“to“the“Swarm's“instance“of“ActionCache“and“not“the“ControlPanelŽ¡‘F(a–?ýwarning“message“will“be“generated“otherwise).ŽŸ8äïhtml:ï html:¦‘<ïcolor push BlackÁlï color popŽŽ‘F¿The–?ýswarmobject“library“has“been“renamed“to“objectbase.‘ úAlthough“the“build“procedureŽ¡‘Fcreates–?ýa“link“to“maintain“compatibility,“applications“should“include“Ž¡‘Finstead–?ýof“.ŽŸ8äïhtml:ï html:¦‘<ïcolor push BlackÁlï color popŽŽ‘F¿Avoid–?ýcalling“globalTkInterp“in“all“future“applications,“it“will“not“be“supportedŽ¡‘Ffrom–?ýversion“1.1“onwards.ŽŸïhtml:ï html:Ÿà‘<ïcolor push BlackÁlï color popŽŽ‘F¿If–?ýthere“exists“a““file,“e.g.‘ ú,“that“file“is“the“advertisedŽ¡‘Finterface–?ýto“LIBRARY,“and“it“will“defined“in“terms“of“protocols.‘ úWhenever“possible,Ž¡‘Fdefine–?ývariables“in“terms“of“the“protocol“they“respond“to:Ž¤8äïhtml:ï html:ïhtml:ï html:¦‘<id–?ý“probeMap;Ž¡ïhtml:ï html:ïhtml:ï html:¦‘<rather–?ýthan“using“a“static“type:Ž¡ïhtml:ï html:ïhtml:ï html:¦‘<ProbeMap‘?ý*probeMap;Ž¡ïhtml:ï html:ïhtml:ï html:¦‘<(One–?ýadvantage“of“this“is“that“fewer“imports“will“be“needed“in“your“application.)ŽŸ8äïhtml:ï html:¤ïhtml:ï html:¦‘0ïcolor push Black3.ï color popŽŽ‘<1.0.2–?ý=>“1.0.3Ž¡ïhtml:ï html:¡ïhtml:ï html:Ÿà‘<ïcolor push BlackÁlï color popŽŽ‘F¿Activity–?ýLibrary:› úReference“Release-Note“#3:˜The“AutoDrop“option“for“any“concurrentŽ¤‘Fgroups–?ýis“automatically“set“to“the“same“as“the“schedule“in“which“it“is“contained.Ž¡‘F(Any–?ýexisting“setting“of“the“option“on“the“concurrent“group“type“is“ignored.)Ž¡‘FSo,–?ýin“1.0.2,“if“you“didn't“set“the“AutoDrop“flag“for“a“concurrentGroup“initializedŽ¡‘Funder–?ýa“schedule,“it“defaulted“to“NO“or“false.ŽŸcïhtml:ï html:Ÿ|s‘<ïcolor push BlackÁlï color popŽŽ‘F¿Random–?ýLibrary:‘ ú13,“14ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘Fïcolor push Blacka.ï color popŽŽ‘RReference–?ýRelease-Note“#13“This“release“includes“Random“v0.7,“written“by“SvenŽ¡‘RThommesen.‘ úThis–?ýversion“adds“several“new“bit“generators“and“distributionsŽ¡‘Rand–?ýrearranges“the“library.– ú(Ref.“$SWARMHOME/src/random/docs/WHATS.CHANGED.in.0.7Ž¡‘Rand‘?ýWHATS.NEW.in.0.7)ŽŸÕSïhtml:ï html:Ÿ ‘Fïcolor push Blackb.ï color popŽŽ‘RReference–?ýRelease-Note“#14:‘ úWith“the“addition“of“the“ability“to“make“use“ofŽ¡‘Rthe–?ýdefault“random“number“generators“and“distributions“such“that“differentŽ¡‘Rruns–?ýstart“with“a“different“seed“or“with“the“same“seed,“the“static“seed“wasŽ¡‘Rchanged.‘ úThis–?ýmeans“that“runs“with“1.0.3“will“not“match“runs“made“with“theŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹4 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Qºâ¿static–?ýseed“for“1.0.2.‘ úThis“is“acceptable“because“the“use“of“the“default“generatorsŽ©‘Qºâand–?ýdistributions“is“ïhtml:ï html:DEPRECATED.ŽºâŸïhtml:ï html:¤Ç‘0ïcolor push Black4.ï color popŽŽ‘<1.0.0–?ý=>“1.0.1Žïhtml:ï html:¡‘0There–?ýshould“not“be“any“imcompatibilities“between“1.0.1“and“1.0.0.‘ úThere“are“a“coupleŽ¦‘<of–?ýchanges“that“affect“the“behavior“of“Swarm,“however.‘ úThe“big“ones“are:Ž¤8äïhtml:ï html:Ÿïhtml:ï html:Ÿ Ž8‘<ïcolor push BlackÁlï color popŽŽ‘F¿The–?ýautomatic“dropping“of“probe“displays“upon“the“dropping“of“an“object“to“whichŽ¦‘Fthose–?ýprobe“displays“were“attached.‘ úThis“could“break“your“application“code“ifŽ¦‘Fyou–?ýleave“in“the“ïhtml:ï html:ó0ˆÛ pcrr7tÂdropProbeDisplaysFor:‘ ú¿message“where“you“drop“such“an“object.Ž¡ïhtml:ï html:Ÿ Ž8‘<ïcolor push BlackÁlï color popŽŽ‘F¿The–?ýdefault“probeMap“has“changed.‘ úThis“is“only“an“issue“when“ïhtml:ï html:ÂcreateProbeDis-Ž¦‘FplayFor:‘ ú¿is–?ýcalled“without“having“previously“created“and“installed“a“probeMapŽ¦‘Ffor–?ýthat“class.‘ úThe“new“behavior“is“to“create“a“probeMap“on-the-fly“that“containsŽ¦‘Fonly–?ýthe“instance“variables“for“that“class.Ž¡ïhtml:ï html:¤ Ž8‘0¾See–?ýthe“ïhtml:ï html:Release“Page‘¼rïhtml:ï html:ŽŸÇ‘0(http://www.santafe.edu/projects/swarm/release.html#changes)Ž©Ç‘0for–?ýother“differences.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¡‘0ïcolor push Black¿5.ï color popŽŽ‘<ïhtml:ï html:¾Beta‘üo¿=>‘?ý1.0.0Žïhtml:ï html:¦‘0As–?ýcan“be“expected“with“any“software“package,“it“is“sometimes“unavoidable“that“changesŽ¤‘<in–?ýthe“functionality“of“the“package“will“cause“incompatibilities“with“earlier“versions.Ž¡‘<This–?ýis“especially“true“when“a“package“is“a“"proof-of-principle"“package“like“Swarm.ŽŸ8äïhtml:ï html:© Ž8‘<We've–?ýmade“an“attempt“to“compile“all“the“problems“a“user“might“have“moving“to“theŽ¡‘Hnew–?ýrelease“and“put“them“here.‘ úPlease“read“this“thoroughly“to“decide“what“youŽ¡‘Hmight–?ýneed“to“do“to“your“app“to“get“it“to“work“with“the“new“release.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘<ïcolor push Blacka.ï color popŽŽ‘HThe–?ýbiggest“and“most“pervasive“problems“will“be“due“to“the“new“ïhtml:ï html:¾random‘üo¿library.Ž¡‘HNotes–?ýon“how“to“deal“with“this“problem“are“provided“in“the“ïhtml:ï html:documentation“forŽ¡‘Hthe‘?ýïhtml:ï html:¾random‘üo¿libraryïhtml:ï html:Ž¤Ç‘<(src/random.html)Ž¡‘<.Ž©ïhtml:ï html:¡‘<ïcolor push Blackb.ï color popŽŽ‘HA–?ýrather“benign“problem“results“from“the“repackaging“of“the“ïhtml:ï html:¾swarmobject‘üo¿library.Ž¤‘HThe–?ýinterface“to“this“library“was“brought“into“sync“with“the“ïhtml:ï html:¾defobj‘¼r¿and“ïhtml:ï html:¾collectionsŽ¡‘H¿libraries.‘ ú(The–?ýrest“of“the“errant“libraries“will“follow“in“a“later“release.)Ž¡‘HThe–?ýsolutions“to“the“problems“associated“with“this“interface“change“are“detailedŽ¡‘Hin–?ýthe“ïhtml:ï html:documentation“for“the“ïhtml:ï html:¾objectbase‘üo¿libraryïhtml:ï html:Ž¤Ç‘<(src/objectbase.html)Ž¡‘<.Ž¦ïhtml:ï html:¡‘<ïcolor push Blackc.ï color popŽŽ‘HThere–?ýare“a“couple“rather“benign“incompatibility“introduced“with“1.0“in“the“newŽ¤‘Hïhtml:ï html:¾activity›üo¿library.‘ úMany–?ýparts“of“ïhtml:ï html:¾activity˜¿have“changed.‘ úBut,“for“the“most“part,Ž¡‘Heverything–?ýworks“exactly“the“same.‘ úFor“details“on“the“incompatibilities“pleaseŽ¡‘Hsee–?ýthe“ïhtml:ï html:documentation“for“the“ïhtml:ï html:¾activity‘üo¿libraryïhtml:ï html:Ž¤Ç‘<(src/activity.html)Ž¡‘<.‘ úBriefly,–?ýthe“incompatibilities“are:ŽŸ8äïhtml:ï html:¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹)c “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Gºâïcolor push BlackÁlï color popŽŽ‘Qºâ¿The–?ýhigh-level“structural“changes“in“the“activity“library“has“led“to“the“renamingŽ¤‘Qºâof–?ýthe“variable“ïhtml:ï html:ÂswarmActivity¿.‘ úIt“is“recommended“that“ïhtml:ï html:Â[self‘ffgetActivity]Ž¡‘Qºâ¿be–?ýused“in“its“place“(if“your“app“even“used“this“variable,“it“was“probablyŽ¡‘Qºâin–?ýthe“ïhtml:ï html:¾BatchSwarm‘¼r¿).‘ úThis“is“a“new“message“and“it“takes“the“place“of“the“ïhtml:ï html:ÂgetSwar-Ž¡‘QºâmActivity–?ý¿message.‘ úBut,“the“obsolete“message“has“been“left“in“place“for“backwardsŽ¡‘Qºâcompatibility.ŽºâŸ8äïhtml:ï html:© ô‘Hïcolor push BlackÁlï color popŽŽ‘R¿The–?ýïhtml:ï html:ÂgetCurrentActivity()“¿macro“is“gone.‘ úIf“you“used“the“old“getCurrentActivity()Ž¡‘Rin–?ýyour“code,“it“won't“work“now.‘ úUse“of“this“macro“was“not“very“widespread,Ž¡‘Rsince–?ýits“main“use“is“to“access“activity“library“internals.‘ úOne“of“the“otherŽ¡‘Rmacros–?ýshould“be“sufficient“for“any“application.ŽŸ8äïhtml:ï html:¦‘<ïcolor push Blackd.ï color popŽŽ‘HThe–?ýfunctionality“of“ïhtml:ï html:¾Zone‘¼r¿s“has“been“greatly“improved“and“expanded“upon.‘ úMostŽ¡‘Hof–?ýthe“aspects“of“the“idea“behind“ïhtml:ï html:¾Zone‘¼r¿s“are“now“in“place.‘ úHowever,“there“isŽ¡‘Hone–?ýincompatibility“that“must“be“noted“in“case“your“code“is“fairly“old.‘ úTheŽ¡‘HdropFrom:› úmessage–?ýhas“been“removed.˜Even“though“it“was“still“present“in“recentŽ¡‘Hreleases,–?ýits“behavior“was“identical“to“drop.‘ úAny“existing“usage“should“be“replacedŽ¡‘Hby–?ýa“simple“drop“message“without“any“zone“argument.‘ úSwarmObject“subclasses“areŽ¡‘Hnow–?ýrestricted“from“accessing“the“zone“that“was“once“contained“in“an“instanceŽ¡‘Hvariable;–?ýthe“message“getZone“must“be“used“instead.ŽŸ€’ïhtml:ï html:Ÿ±ÀObjecti•ÓÅv“e–QëC“Resour°gcesŽŸ‹Æ¼The–‚bmain“technical“skill“required“of“a“Swægarm“user“is“the“ability“to“write“ObjectiÀvÙ e“C“code.‘ ¿Other“recommended“skillsŽ¡include– ºthe“ability“to“use“tools“such“as“gdb“and“emacs.‘ò,FšÙ or“the“record,‘!bif“you“knoÀw“C‘ œand“haÌÐv˜e“some“form“of“e˜xperienceŽ¡in–€either“C++“or“Smalltalk,“then“learning“ObjectiÀvÙ e“C“should“takæge“no“more“than“a“day‘ÿY .ŽŸˆmïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿ Y‘:¿Objective–?ýC“referencesïhtml:ï html:ŽŸ-‘‘:(http://www.santafe.edu/projects/swarm/ObjC/objective-c.html)ŽŸ8äïhtml:ï html:¦‘XNelson's–?ýlist“of“Objective“C“references“on“the“Web.‘ úIncludes“a“10“minuteŽ¡‘Xoverview–?ýto“Objective“C“that“is“most“of“what“you“need“to“know“about“ObjectiveŽ¡‘XC.ŽŸïhtml:ï html:ïhtml:ï html:¤-‘‘:Objective–?ýC“-“Swarm“Styleïhtml:ï html:Ž¡‘:(swarmObjC.html)ŽŸ8äïhtml:ï html:¦‘XThe–?ýSwarm“system“provides“a“few“extensions“to“the“syntax/style“of“Objective-C.Ž¤‘XThis–?ýnote“describes“those“features“which“are“important“to“know“as“a“beginnerŽ¡‘Xand–?ýthose“which“can“be“ignored...ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:Object-Oriented–?ýProgramming“and“the“Objective-C“Languageïhtml:ï html:ŽŸ-‘‘:(http://devworld.apple.com/dev/SWTechPubs/Documents/OPENSTEP/ObjectiveC/objctoc.htm)ŽŸ8äïhtml:ï html:¦‘XAn–?ýexcellent“(online!)‘ úbook“on“Objective“C.“This“is“for“generic“NeXT“ObjectiveŽ¡‘XC:–?ýSwarm“uses“GNU“Objective“C“in“addition“to“our“own“ïhtml:ï html:defobjïhtml:ï html:Ž¤-‘‘X(src/defobj.html)Ž¡‘Xextensions.ŽŸïhtml:ï html:ïhtml:ï html:¡‘:debugging‘?ýtipsïhtml:ï html:Ž¡‘:(debugging.html)ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹;5 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Wºâ¿When–?ýadding“printf()“just“isn't“enough...ŽºâŸ8äïhtml:ï html:ïhtml:ï html:¤ Oç‘:emacs‘?ýtipsïhtml:ï html:Ž©ˆË‘:(emacs-objc.html)ŽŸ8äïhtml:ï html:¡‘XSome–?ýhints“for“editing“Objective“C“code“under“emacs.ŽŸ€’ïhtml:ï html:ŸQÀCor°ge‘QëLibrariesŽŸç¼Swægarm–`¶is“essentially“a“collection“of“libraries“agó7ainst“which“you“link“your“simulation“code.‘»ºThe“folloÀwing“is“a“listŽ¤of–Õ the“those“libraries“which“are“crucial“to“the“proper“e•Ù x“ecution–Õ of“Swšægarm,‘êLand“are“therefore“shipped“with“the“Sw˜armŽ¡distribÌÐution.ŽŸ |éïhtml:ï html:Ÿïhtml:ï html:Ÿj‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Defobj‘?ýLibraryïhtml:ï html:Ž¦‘0(src/defobj.html)Ž¤8äïhtml:ï html:Ÿ Oç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Collections‘?ýLibraryïhtml:ï html:Ž¦‘0(src/collections.html)ŽŸÕSïhtml:ï html:Ÿ³x‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Activity‘?ýLibraryïhtml:ï html:Ž¦‘0(src/activity.html)Ž¡ïhtml:ï html:Ÿ Oç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Objectbase‘?ýLibraryïhtml:ï html:Ž¦‘0(src/objectbase.html)Ž¡ïhtml:ï html:Ÿ Oç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Space‘?ýLibraryïhtml:ï html:Ž¦‘0(src/space.html)Ž¡ïhtml:ï html:Ÿ Oç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Random‘?ýLibraryïhtml:ï html:Ž¦‘0(src/random.html)Ž¤ÕSïhtml:ï html:Ÿ³x‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Simtools‘?ýLibraryïhtml:ï html:Ž¦‘0(src/simtools.html)Ž¡ïhtml:ï html:Ÿ³x‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Graphical–?ýInterface“Library“(tkobjc)ïhtml:ï html:Ž¦‘0(src/tkobjc.html)Ž¤8äïhtml:ï html:Ÿ Oç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Analysis‘?ýToolsïhtml:ï html:Ž¦‘0(src/analysis.html)Ž¡ïhtml:ï html:Ÿ Oç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Probe‘?ýInterfaceïhtml:ï html:Ž¦‘0(src/probing.html)ŽŸ€’ïhtml:ï html:ŸQÀSample‘QëA‘hpplicationŽ¤ç¼The–:ÍfolloÀwing“sample“applications“represent“the“current“best“source“of“guidelines/advice“about“the“structure“of“SwægarmŽŸapplications–€and“the“wægay“in“which“theÙ y“should“be“written“(along“with“ïhtml:ï html:¿intro.htmlïhtml:ï html:Ž¡(intro.html)Ž¦¼).‘ÀEIn–äparticular™Ÿ,‘0the“HeatbÌÐugs“code“has“been“thoroughly“commented“and“demonstrates“some“of“the“main“features“inŽŸSwšægarm.‘2The–~Ïtemplate“application“is“a“good“place“from“which“programmers“can“cop˜y“code“as“a“starting“point“for“theirŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹K¹ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¼initial–×ysimulations.‘ There“is“more“complete“information“(the“screen“shots“are“a“bit“dated)“about“a“feÀw“of“these“demoŽ¤ºâapplications–€in“ïhtml:ï html:¿../examples/ïhtml:ï html:Ž¡ºâ(http://www.santafe.edu/projects/swarm/examples/index.html)Ž¡ºâ¼.ŽºâŸ ´ïhtml:ï html:Ÿïhtml:ï html:ŸáL‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Heatbugs,–?ýa“basic“complex“systemïhtml:ï html:Ž¡‘0(apps/heatbugs.txt)Ž¡‘0:‘ úïhtml:ï html:thoroughly‘?ýcommented!!!Ž©8äïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Template‘?ýapplicationïhtml:ï html:Ž¡‘0(apps/template.txt)Ž¦ïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Simple–?ýmodel“of“a“stock“marketïhtml:ï html:Ž¡‘0(apps/market.txt)Ž¦ïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Mousetrap–?ýmodel“of“fission,“discrete“event“simulationïhtml:ï html:Ž¡‘0(apps/mousetrap.txt)Ž¦ïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Tutorial–?ýis“an“app“that“progressively“moves“from“a“simple“C“implementation“of“aŽ¡‘:CA–?ý(with“bug“agents“on“it)“up“to“a“Swarm-style“application.ïhtml:ï html:Ž¡‘0(apps/tutorial.txt)Ž¦ïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Hello,–?ýWorld!‘ úis“another“simpler“tutorialïhtml:ï html:Ž¡‘0(apps/hello-world.txt)ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹YV “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½A–/T›þªop-DoÊìwn“Intr |oduction“T˜o“ImplementingŽŸ87ïhtml:ï html:Ÿ·gan–/Experiment“Using“SwarmŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:Ÿ ’‘0¿This–?ýdocument“attempts“to“explain“the“logical“structure“of“a“Swarm“experiment“application.Ž¤‘0Starting–?ýwith“a“very“general“outline“of“an“idealized“experimental“procedure,“we“successivelyŽ¡‘0increase–?ýthe“level“of“specification“of“each“stage“of“this“idealized“structure“untilŽ¡‘0we–?ýarrive“at“details“of“an“actual“running“Swarm“application.Ž©8äïhtml:ï html:Ÿ Ô®‘0Along–?ýthe“way,“we“introduce“and“describe“(very“briefly)“some“of“the“tools“currentlyŽ¡‘0available–?ýin“Swarm“to“help“users“build“experiments.‘ úThe“tools“presented“here“areŽ¡‘0only–?ýsuggestive:‘ úthe“Swarm“library“documentation“and“example“applications“will“giveŽ¡‘0a–?ýmore“detailed“view“of“using“specific“components“of“Swarm.Ž¦ïhtml:ï html:© Ô®‘0These–?ýtools“are“more“fully“documented“in“the“appropriate“library“directories.‘ úThisŽ¡‘0high-level–?ýoverview“skips“much“of“the“detail“in“an“effort“to“illustrate“the“logicalŽ¡‘0structure–?ýof“a“Swarm“application“and“to“provide“some“motivation“for“why“things“areŽ¡‘0done–?ýthe“way“they“are“in“the“example“applications.ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸÉüÀHoÓÅw–Qëwe'll“pr°goceedŽŸkÇ¿In–?ýthe“following,“we“will“start“out“with“a“very“high-level“outline/abstraction“of“the“"genericŽ¡form"–?ýof“an“experimental“procedure.‘ úThen“we“will“increase“the“magnification“on“each“pieceŽ¡of–?ýthe“outline“until“we“reach“specific“details“of“Swarm“code.‘ úIf“you“compare“the“gross“structureŽ¡of–?ýthe“example“applications“you“will“see“that“despite“the“differences“in“detail,“the“overallŽ¡architecture–?ýof“Swarm“applications“adheres“to“the“general“abstraction“of“an“experimental“procedure.ŽŸ—ïhtml:ï html:¦‘0The–?ýapplication“we“will“use“as“an“example“is“the“Heatbugs“application.‘ úThe“sourceŽ¡‘0code–?ýfor“that“example“is“a“thoroughly“commented“application“and“intended“to“be“readŽ¡‘0by–?ýnew“Swarm“programmers.› úIt“can“be“a“useful“template“to“start“from:˜so“can“theŽ¡‘0very-stripped-down–?ý"template"“application.‘ úWe“recommend“that“you“gradually“ease“yourselfŽ¡‘0into–?ýthe“Swarm“perspective“by“experimenting“with“the“example“applications“and“branchingŽ¡‘0out–?ýby“modifying“them“in“various“ways“until“you“catch“on“to“the“conceptual“style“ofŽ¡‘0a–?ýSwarm“Experiment.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Mag–?ý1x:‘ úExperimental“Procedure“in“a“Computerïhtml:ï html:Ž¤8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Mag–?ý2x:‘ úBasis“of“Swarm“Computationïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Mag–?ý3x:‘ úSwarm“Structuresïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Mag–?ý4x:‘ úSketch“of“Codeïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Conclusionïhtml:ï html:ŽŸ‘0„¤ŽŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ bK “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸçåÀMag–Që1x:‘[UExperimental“Pr•°gocedur“e–Qëin“a“ComputerŽŸKÆ¿At–?ýthe“highest“level“of“abstraction“(“=“the“lowest“level“of“magnification),“most“experimentsŽŸlook–?ýlike“this:ŽŸ ^5ïhtml:ï html:Ÿïhtml:ï html:Ÿí‘‘0ïcolor push Black1.ï color popŽŽ‘<Set–?ýup“the“physical“system“to“be“studiedŽ¤8äïhtml:ï html:© ´‘0ïcolor push Black2.ï color popŽŽ‘<Set–?ýup“and“calibrate“the“instrumentationŽ¡ïhtml:ï html:¦‘0ïcolor push Black3.ï color popŽŽ‘<Run–?ýthe“experimental“system“and“record“the“outputs“of“the“instrumentationŽ¡ïhtml:ï html:¦‘0ïcolor push Black4.ï color popŽŽ‘<Analyze‘?ýresultsŽ¡ïhtml:ï html:¦‘0ïcolor push Black5.ï color popŽŽ‘<If–?ýnot“happy“with“the“results:Ž¡ïhtml:ï html:Ÿïhtml:ï html:¦‘<ïcolor push BlackÁlï color popŽŽ‘F¿Change–?ýexperimental“and“instrumental“setupŽ¡ïhtml:ï html:¦‘<ïcolor push BlackÁlï color popŽŽ‘F¿Go–?ýto“3ŽŸ ¬ïhtml:ï html:ŸÐå‘0ïcolor push Black6.ï color popŽŽ‘<Publish–?ýpaper“->“tenure“->“fame“->“etc.....ŽŸí‘The–?ýimportant“part“of“step“6)“is“that“the“published“paper“includes“enough“detail“about“theŽ¤experimental–?ýsetup“and“how“it“was“run“so“that“other“labs“with“access“to“the“same“equipmentŽ¡can–?ýrecreate“the“experiment“and“test“the“repeatability“of“the“results.‘ úThis“is“hardly“ïhtml:ï html:¾everŽ¡¿done–?ý(or“even“possible)“in“the“context“of“experiments“run“in“computers,“and“the“crucial“processŽ¡of–?ýindependent“verification“via“replication“of“results“is“almost“unheard“of“in“computer“simulation.Ž¡One–?ýgoal“of“Swarm“is“to“bring“simulation“writing“up“to“a“higher“level“of“expression,“writingŽ¡applications–?ýwith“reference“to“a“standard“set“of“simulation“tools.ŽŸ8äïhtml:ï html:¦‘0First,–?ýlet's“look“at“what“happens“when“we“port“the“above“stages“into“the“world“ofŽ¡‘0a–?ýcomputer.‘ úIn“a“computer,“you“don't“just“drag“the“pieces“of“your“experiment“in“fromŽ¡‘0the–?ýoutside“world“and“hook“them“up.‘ úYou“have“to“create“a“world“with“space“and“time,Ž¡‘0a–?ýbunch“of“objects“in“that“world“(stuff“to“study“and“stuff“to“look“at“it“with),“schedulesŽ¡‘0of–?ýevents“over“those“objects,“all“sorts“of“computer“widgetry“to“interact“with“thatŽ¡‘0artificial–?ýworld“and“to“manage“multiple“experimental“runs“and“the“data“that“they“generate,Ž¡‘0and–?ýso“forth.‘ úIn“other“words,“in“a“computer,“one“usually“has“to“first“*create*“fromŽ¡‘0scratch–?ýall“of“the“bits“and“pieces“of“the“experimental“setup“-“the“virtual“equivalentŽ¡‘0of–?ýbeakers,“bunsen“burners,“microscopes“etc.ŽŸ8äïhtml:ï html:¦‘0Perhaps–?ýthe“most“important“difference“between“an“experiment“in“the“"real"“world“andŽ¡‘0an–?ýexperiment“inside“of“a“computer“is“the“nature“of“time.‘ úIn“the“real“world,“everythingŽ¡‘0in–?ýone's“experimental“setup“is“moved“forward“in“time“via“a“very“concurrency“courtesyŽ¡‘0of–?ýthe“laws“of“physics.‘ úIn“a“computer“experiment,“however,“the“experimenter“has“toŽ¡‘0explicitly–?ýmove“every“object“in“his/her“artificial“universe“forward“in“time,“makingŽ¡‘0sure–?ýthat“everything“remains“within“some“well-understood“state“of“synchronization.Ž¡‘0Many–?ýfundamental“problems“in“computer“science“have“arisen“in“the“course“of“tryingŽ¡‘0to–?ýunderstand“how“to“control“and“use“concurrency.‘ úFurthermore,“most“people“who“implementŽ¡‘0computer–?ýsimulations“aren't“even“aware“of“the“subtle,“but“quite-possibly“dominating,Ž¡‘0impacts–?ýof“assumptions“that“they“aren't“even“aware“that“they“are“making“about“concurrencyŽ¡‘0in–?ýtheir“model“when“they“code“it“up“and“run“it.ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ pÍ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿Therefore,–?ýa“very“important“aspect“of“setting“up“an“experiment“in“a“computer“is“howŽ¤‘/ºâone–?ýweaves“the“multiple“threads“of“time“that“must“be“woven“together“coherently“inŽ¡‘/ºâorder–?ýto“produce“reliable,“repeatable“results.‘ úMuch“of“our“work“on“Swarm“has“beenŽ¡‘/ºâdevoted–?ýto“not“only“making“the“task“of“managing“concurrency“manageable,“but“towardsŽ¡‘/ºâmechanisms–?ýto“make“people“aware“that“they“are“ïhtml:ï html:¾always‘üo¿making“implicit“assumptionsŽ¡‘/ºâabout–?ýhow“multiple“threads“of“time“are“interacting“with“one“another“in“their“experimentalŽ¡‘/ºâsetups.‘ úSwarm–?ýforces“experimenters“to“make“their“concurrency“assumptions“explicit,Ž¡‘/ºâso–?ýthat“others“can“reproduce“their“results“by“implementing“the“same“assumptions“aboutŽ¡‘/ºâthe–?ýflow“of“time.ŽŸ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:ŸpFÀMag–Që2x:‘[UBasis“of“Swarm“ComputationŽŸ¿Here–?ýis“a“first“approximation“to“embedding“the“above“outline“of“an“experimental“procedure“inŽ¡Swarm‘?ýcode:ŽŸ ^5ïhtml:ï html:©³Ü‘0Swarm–?ýis“implemented“in“the“Object-Oriented“Programming“language“Objective-C.“ComputationŽ¡‘0in–?ýa“Swarm“application“takes“place“by“having“objects“send“messages“to“each“other.Ž¡‘0The–?ýbasic“message“syntax“isŽŸ8äïhtml:ï html:Ÿïhtml:ï html:Ÿ zø‘0Â[targetObject–ffmessage“Arg1:“var1“Arg2:“var2]Ž¦¿Where–?ý"targetObject"“is“the“recipient“of“the“message,“"messageArg1:Arg2:"“is“the“message“toŽ¡send–?ýto“that“object,“and“"var1",“"var2",“etc,“are“arguments“to“pass“along“with“the“message.Ž¡Objective–?ýC's“messages“are“keyword/value“oriented,“which“is“why“the“message“name“"messageArg1:Arg2:"Ž¡is–?ýinterspersed“with“the“arguments.Ž©8äïhtml:ï html:Ÿ zø‘0The–?ýwhole“idea“of“Swarm“is“to“provide“an“execution“context“within“which“a“large“numberŽ¡‘0of–?ýobjects“can“"live“their“lives"“and“interact“with“one“another“in“a“distributed,Ž¡‘0concurrent–?ýmanner.‘ úFurthermore,“we“wish“to“insulate“the“user“from“having“to“masterŽ¡‘0all–?ýof“the“highly“baroque“computer-science“wizardry“usually“required“to“implementŽ¡‘0such–?ýmassively“distributed“systems“of“autonomous“agents“reliably“and“robustly.Ž¦ïhtml:ï html:© zø‘0In–?ýthe“context“of“the“Swarm“simulation“system,“the“generic“outline“of“an“experimentalŽ¡‘0procedure–?ýtakes“the“following“form:ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push Black1.ï color popŽŽ‘<Create–?ýan“artificial“universe“replete“with“space,“time,“and“objects“that“can“beŽ¡‘<located,–?ýwithin“reason,“to“certain“"points"“in“the“overall“structure“of“space“andŽ¡‘<time–?ýwithin“the“universe.,“and“allow“these“objects“to“determine“their“own“behaviorŽ¡‘<according–?ýto“their“own“rules“and“internal“state“in“concert“with“sampling“the“stateŽ¡‘<of–?ýthe“world,“usually“only“sparsely.ŽŸ8äïhtml:ï html:¦‘0ïcolor push Black2.ï color popŽŽ‘<Create–?ýa“number“of“objects“which“will“serve“to“observe,“record,“and“analyze“dataŽ¡‘<produced–?ýby“the“behavior“of“the“objects“in“the“artificial“universe“implementedŽ¡‘<in–?ýstep“1)ŽŸ8äïhtml:ï html:¦‘0ïcolor push Black3.ï color popŽŽ‘<Run–?ýthe“universe,“moving“both“the“simulation“and“observation“objects“forward“inŽ¡‘<time–?ýunder“some“explicit“model“of“concurrency.ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹€Ò “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâïcolor push Black¿4.ï color popŽŽ‘;ºâInteract–?ýwith“the“experiment“via“the“data“produced“by“the“instrumentation“objectsŽ¤‘;ºâto–?ýperform“a“series“of“controlled“experimental“runs“of“the“system.Žºâ©8äïhtml:ï html:Ÿ wm‘0ïcolor push Black5.ï color popŽŽ‘<Depending–?ýon“what“is“observed“in“stage“4),“alter“the“experimental“or“instrumentalŽ¡‘<"apparatus"–?ýand“go“back“to“3).Ž¦ïhtml:ï html:© wm‘0ïcolor push Black6.ï color popŽŽ‘<Publish–?ýpaper“*including*“detailed“specification“of“the“experimental“set-up“soŽ¡‘<that–?ýothers“can“recreate“your“experiment“and“verify“your“results.ŽŸ‘0„¤ŽŽ¤G®ïhtml:ï html:Ÿl»ÀMag–Që3x:‘[USwarm“Structur°gesŽŸV4¿Swarm–?ýapplications“are“structured“around“the“concept“of“the“ïhtml:ï html:¾Swarm‘¼r¿.‘ úïhtml:ï html:¾Swarms‘üo¿are“the“basic“buildingŽ¡blocks–?ýof“Swarm“simulations:‘ úa“ïhtml:ï html:¾Swarm‘üo¿is“a“combination“of“a“collection“of“objects“and“a“scheduleŽ¡of–?ýactivity“over“those“objects.‘ úThe“collection“are“like“the“matter“of“the“Swarm“and“the“scheduleŽ¡is–?ýlike“the“arrow“of“time“moving“the“objects“forward.ŽŸŸJïhtml:ï html:Ÿ¿óÓßŒ˜ff ptmb7tÅModel‘™™SwarmsŽŸT(¿For–?ýour“current“demos,“Swarm“applications“contain“two“swarms.‘ úAt“the“core“is“the“ïhtml:ï html:¾model“swarm‘¼r¿,Ž¤the–?ýSwarm“that“encapsulates“the“simulated“model.‘ úEverything“in“the“model“swarm“correspondsŽ¡to–?ýobjects“in“the“world“being“modeled.‘ úFor“instance,“in“Heatbugs“the“HeatbugModelSwarm“containsŽ¡a–?ýcollection“of“Heatbug“agents,“a“HeatSpace“to“represent“a“physical“property“of“the“world,Ž¡and–?ýa“Grid2d“to“store“agent“position.ŽŸ Ü»ïhtml:ï html:¦‘0In–?ýaddition“to“the“object“collection,“the“model“swarm“also“contains“a“schedule“ofŽ¡‘0activity–?ýon“the“model.‘ úThe“schedule“defines“the“effect“of“passing“time“on“the“model.Ž¡‘0For–?ýthe“simple“heatbugs“schedule,“the“execution“is“simply“to“update“the“HeatSpaceŽ¡‘0(diffusing–?ýheat“across“the“world)“and“then“telling“each“Heatbug“agent“to“move“itself.ŽŸ8äïhtml:ï html:¦‘0Model–?ýswarms“consist“of“a“set“of“inputs“and“outputs.‘ úThe“inputs“to“the“HeatbugModelSwarmŽ¡‘0are–?ýmodel“parameters:‘ úthings“like“the“size“of“the“world,“the“number“of“HeatBugs,Ž¡‘0and–?ýthe“diffusion“rate“of“heat.‘ úThe“outputs“of“the“HeatbugModelSwarm“are“the“observablesŽ¡‘0of–?ýthe“model:‘ úthe“individual“Heatbugs,“the“distribution“of“heat“across“the“world,Ž¡‘0etc.ŽŸffïhtml:ï html:Ÿ÷ÿÅObser•Û$v“erSwarmsŽŸT(¿The–?ýmodel“swarm“alone“defines“the“simulated“world.‘ úBut“an“experiment“does“not“just“consistŽ¡of–?ýthe“objects“being“experimented“upon,“it“also“includes“the“experimental“apparatus“used“forŽ¡observation–?ýand“measurements.‘ úIn“Swarm“computer“simulations,“those“observation“objects“areŽ¡placed–?ýin“an“ïhtml:ï html:¾observer“swarm‘¼r¿.ŽŸ Ü»ïhtml:ï html:¦‘0The–?ýmost“important“object“in“an“observer“swarm“is“the“model“swarm“that“is“being“studied.Ž¡‘0The–?ýmodel“swarm“is“one“component“of“the“observer,“kind“of“like“a“little“world“in“aŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹F “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿petri–?ýdish“on“the“lab“bench.‘ úOther“observer“objects“can“then“input“data“into“theŽ¤‘/ºâmodel–?ýswarm“(setting“simulation“parameters,“for“instance)“and“read“data“out“of“theŽ¡‘/ºâmodel–?ýswarm“(collecting“statistics“of“the“behavior“of“agents).Žºâ©8äïhtml:ï html:Ÿ ‘0Just–?ýas“in“setting“up“a“model“swarm,“an“observer“swarm“has“a“collection“of“objectsŽ¡‘0(the–?ýinstrumentation),“a“schedule“of“activity,“and“a“set“of“inputs“and“outputs.‘ úTheŽ¡‘0activity–?ýof“the“observer“schedule“is“to“drive“data“collection“-“read“this“number“outŽ¡‘0of–?ýthe“model,“draw“it“on“a“graph.‘ úThe“inputs“to“the“observer“swarm“are“configurationsŽ¡‘0of–?ýthe“observer“tools:› úwhat“sorts“of“graphs“to“generate,“for“instance.˜The“outputsŽ¡‘0are–?ýthe“observations.ŽŸïhtml:ï html:ŸEþ‘0When–?ýrunning“in“graphics“mode,“the“observer“swarm“objects“are“largely“used“to“mediateŽ¡‘0user–?ýinterface.‘ úFor“instance,“in“Heatbugs“the“HeatbugObserverSwarm“creates“RasterŽ¡‘0widgets,–?ýEZGraphs,“and“Probes.‘ úAll“of“these“objects“are“connected“into“the“HeatbugModelŽ¡‘0swarm–?ýto“read“data,“and“to“graphical“interface“objects“so“the“human“sitting“in“frontŽ¡‘0of–?ýthe“computer“can“observe“the“world.Ž¦ïhtml:ï html:Ÿ ‘0Interactive,–?ýgraphical“experimentation“with“models“is“useful“for“coming“up“with“intuitions.Ž¡‘0But–?ýfor“serious“experimentation“it“is“necessary“to“collect“statistics,“which“meansŽ¡‘0doing–?ýmany“runs“and“storing“data“for“analysis.‘ úAs“an“alternative“to“a“graphical“observerŽ¡‘0swarm,–?ýyou“can“also“create“ïhtml:ï html:¾batch“swarms‘¼r¿,“observer“swarms“that“are“intended“to“beŽ¡‘0run–?ýwithout“any“interaction“at“all.‘ úInstead“of“putting“up“fancy“graphics,“batch“swarmsŽ¡‘0read–?ýdata“from“files“to“control“the“model“and“write“the“data“out“to“other“files“forŽ¡‘0analysis.‘ úThe–?ýkey“here“is“that“the“model“swarm“used“in“the“batch“swarm“is“the“exactŽ¡‘0same–?ýmodel“as“that“used“in“a“graphical“observer“swarm:‘ úthe“only“difference“is“whatŽ¡‘0tools–?ýthe“observer“(batch“or“graphical)“connects“to“the“model.Ž©ŸJïhtml:ï html:ŸTÈÅSummaryŽŸéÕ¿Multiple–?ýSwarms“are“used“to“create“an“experimental“apparatus“and“control“it.‘ úThe“use“of“multipleŽ¡Swarms–?ýis“not“restricted“only“to“this“use,“though:‘ úin“particular,“a“model“Swarm“could“itselfŽ¡contain–?ýits“own“subswarms,“building“a“hierarchical“simulation.‘ úIn“future“Swarm“development,Ž¡we–?ýintend“to“use“the“power“of“the“multiple“Swarm“modeling“approach“to“build“complicated“andŽ¡flexible‘?ýmodels.ŽŸ£×ïhtml:ï html:Ÿ‘0„¤ŽŽ¤G®ïhtml:ï html:ŸhÀMag–Që4x:‘[USkÓÅetch“of“CodeŽŸëá¿Now–?ýthat“we“have“multiple“Swarms“and“an“experimental“apparatus,“it's“time“to“learn“how“to“useŽ¡the–?ýobjects“themselves“inside“an“application.› úSome“examples“are“provided“here:˜to“understandŽ¡this–?ýbetter,“it“will“be“necessary“to“read“through“example“applications“and“the“library“documentation.Ž¡These–?ýexamples“come“from“the“Heatbugs“application.Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ œý “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅBuilding–™™a“Model“SwarmŽŸšºâ¿The–?ýkey“component“of“a“simulation“is“the“model“Swarm.‘ úHere“is“the“definition“of“a“HeatbugModelSwarm,Ž©ºâfrom‘?ýHeatbugModelSwarm.hŽºâŸ Ü»ïhtml:ï html:Ÿ $ß‘0Â@interface–ffHeatbugModelSwarm“:“Swarm“ó©±Ê cmsy9ÇfŽ¤]Ã‘5ffÂint–ffnumBugs;“//“simulation“parametersŽ¡‘5ffdouble‘ffevaporationRate;Ž¡‘5ffdouble‘ffdiffuseConstant;Ž¡‘5ffint–ffworldXSize,“worldYSize;Ž¡‘5ffint–ffminIdealTemp,“maxIdealTemp;Ž¡‘5ffint–ffminOutputHeat,“maxOutputHeat;Ž¡‘5ffdouble‘ffrandomMoveProbability;Ž¡¡‘5ffid–ffmodelActions;“//“scheduling“data“structuresŽ¡‘5ffid‘ffmodelSchedule;Ž¡¡‘5ffid–ffheatbugList;“//“list“of“all“the“heatbugsŽ¡‘5ffGrid2d–ff*“world;“//“objects“representingŽ¡‘5ffHeatSpace–ff*“heat;“//“the“worldŽ¡‘0ÇgŽ¡¡‘0Â-getHeatbugList;–ff//“access“methods“into“theŽ¡‘0-(Grid2d–ff*)“getWorld;“//“model“swarm.“These“methodsŽ¡‘0-(HeatSpace–ff*)“getHeat;“//“allow“the“model“swarm“toŽ¡‘5ff//–ffbe“observed.Ž¡¡‘0+createBegin:–ff(id)“aZone;“//“extra“methods“youŽ¡‘0-createEnd;–ff//“provide“for“SwarmsŽ¡‘0-buildObjects;Ž¡‘0-buildActions;Ž¡‘0-activateIn:–ff(id)“swarmContext;Ž¡¿The–?ýfirst“section“of“code“says“that“a“HeatbugModelSwarm“is“a“kind“of“Swarm.‘ úHeatbugModelSwarmŽ¦inherits–?ýa“lot“of“behavior“from“generic“Swarm,“but“also“adds“new“variables“and“methods.Ž¤8äïhtml:ï html:Ÿ $ß‘0The–?ýnew“variables“are“enclosed“in“the“braces“in“the“definition“of“HeatbugModelSwarm.Ž¦‘0They–?ýare“split“into“three“general“classes“of“things:‘ úsimulation“parameters,“scheduleŽ¦‘0data–?ýstructures,“and“objects“in“the“world.‘ úThis“is“a“typical“sort“of“model“swarm.Ž¡ïhtml:ï html:Ÿ $ß‘0Finally,–?ýa“HeatbugModelSwarm“defines“new“methods.‘ úThe“first“few“methods“are“usedŽ¦‘0to–?ýallow“the“model“to“be“observed:‘ úa“HeatbugModelSwarm“will“give“out“its“list“ofŽ¦‘0Heatbugs,–?ýfor“instance,“or“its“HeatSpace.‘ úObservers“use“these“methods“to“monitorŽ¦‘0the‘?ýmodel.ŽŸïhtml:ï html:Ÿ]Ã‘0In–?ýaddition“to“the“observation“methods,“there“are“several“Swarm-specific“methods“forŽ¦‘0the–?ýbuilding“of“Swarms.› úThese“are“fairly“stereotyped.˜The“ïhtml:ï html:ÂcreateBegin“¿and“ïhtml:ï html:Âcre-Ž¦‘0ateEnd–?ý¿messages“are“used“to“create“the“Swarm“object“itself.‘ úïhtml:ï html:ÂbuildObjects“¿buildsŽ¦‘0the–?ýmodel“objects,“and“ïhtml:ï html:ÂbuildActions“¿builds“the“model“schedule“-“more“on“these“later.Ž¦‘0Finally,–?ýïhtml:ï html:ÂactivateIn“¿arranges“for“the“execution“machinery“to“execute“the“Swarm“itself.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ª@ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ÅDening–™™an“AgentŽŸš¿The–?ýagents“are“typically“the“real“focus“of“a“modeling“effort.‘ úMost“of“the“work“in“a“simulationŽ¤comes–?ýin“defining“the“agent“behavior“so“that“the“computer“agents“resemble“the“real“world“phenomenaŽ¡you–?ýare“trying“to“create.ŽŸ Ü»ïhtml:ï html:© $ß‘0In–?ýthe“case“of“Heatbugs,“agents“are“pretty“simple.‘ úHere“is“their“definition,“fromŽ¡‘0Heatbug.h:ŽŸ8äïhtml:ï html:¦‘0Â@interface–ffHeatbug:“SwarmObject“ÇfŽ¤]Ã‘5ffÂdouble–ffunhappiness;“//“my“current“unhappinessŽ¡‘5ffint–ffx,“y;“//“my“spatial“coordinatesŽ¡‘5ffHeatValue–ffidealTemperature;“//“my“ideal“temperatureŽ¡‘5ffHeatValue–ffoutputHeat;“//“how“much“heat“I“put“outŽ¡‘5fffloat–ffrandomMoveProbability;“//“chance“of“moving“randomlyŽ¡¡‘5ffGrid2d–ff*“world;“//“the“world“I“live“inŽ¡‘5ffint–ffworldXSize,“worldYSize;“//“how“big“that“world“isŽ¡‘5ffHeatSpace–ff*“heat;“//“the“heat“for“the“worldŽ¡‘5ffColor–ffbugColor;“//“my“colour“(display)Ž¡‘0ÇgŽ¡¡‘0Â-setWorld:–ff(Grid2d“*)“w“Heat:“(HeatSpace“*)“h;“//“which“world“are“we“in?Ž¡‘0-createEnd;Ž¡¡‘0-(double)‘ffgetUnhappiness;Ž¡¡‘0-setIdealTemperature:–ff(HeatValue)“i;Ž¡‘0-setOutputHeat:–ff(HeatValue)“o;Ž¡‘0-setRandomMoveProbability:–ff(float)“p;Ž¡‘0-setX:–ff(int)“x“Y:“(int)“y;“//“bug's“positionŽ¡‘0-setBugColor:–ff(Color)“c;“//“bug's“colour“(display)Ž¡¡‘0-step;Ž¡¡‘0-drawSelfOn:–ff(Raster“*)“r;Ž¡¿Heatbug–?ýis“a“subclass“of“SwarmObject.‘ úSwarmObjects“have“very“little“behavior“of“their“ownŽ¤-–?ýthey“are“defined“as“the“root“class“of“most“objects“and“control“computer“science“aspects“likeŽ¡memory–?ýallocation“and“probability.ŽŸ8äïhtml:ï html:¦‘0Heatbug–?ýcarry“with“them“a“variety“of“state“variables.‘ úFor“instance,“each“HeatbugŽ¡‘0has–?ýa“notion“of“its“ideal“temperature,“which“will“affect“it's“behavior.‘ úIn“addition,Ž¡‘0Heatbugs–?ýhave“variables“that“let“them“know“about“the“world:‘ úthese“agents“are“storingŽ¡‘0references–?ýto“the“HeatSpace“object,“for“example.ŽŸ8äïhtml:ï html:¦‘0Most–?ýof“the“Heatbug“methods“have“to“do“with“setting“up“the“agents“state“-“the“inputsŽ¡‘0to–?ýa“Heatbug.‘ úEvery“heatbug“must“set“up“its“world“and“heat“objects,“via“the“ïhtml:ï html:Âset-Ž¡‘0World:Heat:– ú¿method.“In–?ýaddition“when“Heatbugs“are“created“they“have“their“idealŽ¡‘0temperature–?ýset,“their“output“heat,“etc.› úHeatbugs“are“also“observable.˜HeatbugsŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹µ¥ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿define–?ýa“ïhtml:ï html:ÂgetUnhappiness“¿method“-“the“unhappiness“is“the“major“measurable“aspect“ofŽ¤‘/ºâa–?ýheatbug,“how“well“optimized“it“is“at“the“moment.‘ úThey“also“have“a“ïhtml:ï html:ÂdrawSelfOn“¿methodŽ¡‘/ºâthat–?ýdirects“the“heatbug“to“draw“itself“on“the“specified“graphics“widget.ŽºâŸ8äïhtml:ï html:© B‘0Finally,–?ýand“most“importantly,“a“Heatbug“has“a“ïhtml:ï html:Âstep“¿method.‘ úïhtml:ï html:Âstep“¿is“where“the“HeatbugsŽ¡‘0behavior–?ýis“defined:‘ úevery“time“the“Heatbug“is“told“to“step“it“performs“its“internalŽ¡‘0calculations,–?ýchoosing“where“to“move.‘ úEach“heatbug“is“told“to“ïhtml:ï html:Âstep“¿when“appropriateŽ¡‘0by–?ýthe“model“schedule.‘ úThe“code“for“ïhtml:ï html:Âstep“¿is“the“real“intellectual“input“into“theŽ¡‘0model,–?ýand“is“worth“reading“as“an“example“of“an“agent's“behavior.ŽŸŸJïhtml:ï html:ŸHðÅBuilding‘™™AgentsŽŸÝý¿Now–?ýthat“Heatbugs“have“been“defined,“the“model“swarm“needs“to“create“them.‘ úThis“code“fragmentŽ¡is–?ýfrom“the“ïhtml:ï html:ÂbuildObjects“¿method“on“HeatbugModelSwarm.ŽŸ Ü»ïhtml:ï html:¦‘0Â//–ffA“loop“to“create“a“bunch“of“heatbugs.Ž¤:&‘0for–ff(i“=“0;“i“<“numBugs;“i++)“ÇfŽ¡‘5ffÂHeatbug–ff*“hbug;Ž¡‘5ffint–ffidealTemp,“outputHeat;Ž¡¡‘5ff//–ffChoose“a“random“ideal“temperature,“output“heat“from“the“specifiedŽ¡‘5ff//–ffrange“(model“parameters).Ž¡‘5ffidealTemp–ff=“[uniformRandom“rMin:“minIdealTemp“Max:“maxIdealTemp];Ž¡‘5ffoutputHeat–ff=“[uniformRandom“rMin:“minOutputHeat“Max:“maxOutputHeat];Ž¡¡‘5ff//–ffCreate“the“heatbug,“set“the“creation“time“variablesŽ¡‘5ffhbug–ff=“[Heatbug“createBegin:“[self“getZone]];Ž¡‘5ff[hbug–ffsetWorld:“world“Heat:“heat];Ž¡‘5ffhbug–ff=“[hbug“createEnd];Ž¡¡‘5ff//–ffAdd“the“bug“to“the“end“of“the“list.Ž¡‘5ff[heatbugList–ffaddLast:“hbug];Ž¡¡‘5ff//–ffNow“initialize“the“rest“of“the“heatbug's“state.Ž¡‘5ff[hbug–ffsetIdealTemperature:“idealTemp];Ž¡‘5ff[hbug–ffsetOutputHeat:“outputHeat];Ž¡‘5ff[hbug–ffsetX:“[uniformRandom“rMax:“worldXSize]“//“random“positionŽ¡‘5ffY:–ff[uniformRandom“rMax:“worldYSize]];Ž¡‘0ÇgŽŸÔ¿The–?ýdetails“of“this“code“are“best“explained“in“reading“the“documentation“for“the“libraries.Ž¤G®Essentially,–?ýwe“first“generate“two“random“numbers:‘ úan“ideal“temperature“and“an“output“heatŽ¡for–?ýthe“new“Heatbug.‘ úWe“then“create“the“Hheatbug“itself“with“ïhtml:ï html:ÂcreateBegin“¿and“fill“in“theŽ¡required–?ýparameters“of“world“and“heat.‘ úOnce“those“are“set,“we“can“send“ïhtml:ï html:ÂcreateEnd“¿to“the“HeatbugŽ¡and–?ýit“is“finished“being“created.‘ úAfter“it's“done“being“created“we“add“it“into“a“list“of“HeatbugsŽ¡in–?ýthe“model“and“set“a“few“parameters“on“it“like“the“ideal“temperature“and“the“initial“position.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹À^ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ÅBuilding–™™Space“objectsŽ©ý‹¿In–?ýSwarm,“spaces“are“really“just“another“kind“of“agent.‘ úIn“the“heatbugs“model“we“create“aŽ¤HeatSpace,–?ýa“subclass“of“a“diffusion“object“from“the“Swarm“space“libaries“(specified“in“HeatSpace.m).Ž¡Here–?ýis“the“code“from“ïhtml:ï html:ÂbuildObjects“¿in“the“HeatbugModelSwarmŽŸ Ü»ïhtml:ï html:Ÿ Ð‘0Âheat–ff=“[HeatSpace“createBegin:“[self“getZone]];Ž¤Y´‘0[heat–ffsetSizeX:“worldXSize“Y:“worldYSize];Ž¡‘0[heat–ffsetDiffusionConstant:“diffuseConstant];Ž¡‘0[heat–ffsetEvaporationRate:“evaporationRate];Ž¡‘0heat–ff=“[heat“createEnd];ŽŸ¡b¿the–?ýobject“is“created,“a“few“parameters“are“set,“and“then“the“creation“is“finalized.ŽŸŸJïhtml:ï html:Ÿh~ÅScheduling–™™a“Model“SwarmŽ¦¿Once–?ýall“of“the“simulated“objects“are“created“in“ïhtml:ï html:ÂbuildObjects¿,“the“next“task“is“to“scheduleŽ©them–?ýin“the“method“ïhtml:ï html:ÂbuildActions¿.ŽŸÀ ïhtml:ï html:Ÿ<ë‘0ÂmodelActions–ff=“[ActionGroup“create:“[self“getZone]];Ž¡‘0[modelActions–ffcreateActionTo:“heat“message:“M(stepRule)];Ž¡‘0[modelActions–ffcreateActionForEach:“heatbugList“message:“M(step)];Ž¡‘0[modelActions–ffcreateActionTo:“heat“message:“M(updateLattice)];Ž¡¡‘0modelSchedule–ff=“[Schedule“createBegin:“[self“getZone]];Ž¡‘0[modelSchedule–ffsetRepeatInterval:“1];Ž¡‘0modelSchedule–ff=“[modelSchedule“createEnd];Ž¡‘0[modelSchedule–ffat:“0“createAction:“modelActions];Ž¡¿The–?ýheatbug“model“schedule“actually“consists“of“two“components:‘ úan“ActionGroup“called“ïhtml:ï html:Âmod-Ž¦elActions–?ý¿and“a“Schedule“called“ïhtml:ï html:ÂmodelSchedule¿.‘ úThe“ActionGroup“is“a“tightly“coupled“listŽ¦of–?ýthree“messages:‘ úevery“time“the“action“group“is“executed,“it“will“send“three“messages“inŽ¦a‘?ýrow:ŽŸïhtml:ï html:¡‘0Â[heat‘ffstepRule];Ž¡‘0[heatbugList–ffforEach:“step];Ž¡‘0[heat‘ffupdateLattice];ŽŸ¡b¿The–?ýActionGroup“alone“specifies“three“messages“to“send“-“in“order“to“put“it“in“the“simulation,Ž¤G®that–?ýActionGroup“is“then“dropped“into“a“Schedule.‘ úThe“Schedule“itself“only“has“one“actionŽ¡-–?ýto“execute“ïhtml:ï html:ÂmodelActions“¿itself.› úThat“action“takes“place“at“time“0.˜But“because“we've“setŽ¡a–?ýrepeat“interval“on“the“schedule“of“1,“the“schedule“itself“loops,“executing“every“1“time“step.Ž¡The–?ýfinal“result“is“that“ïhtml:ï html:ÂmodelActions“¿is“executed“at“time“0,“time“1,“etc.ŽŸÉóïhtml:ï html:Ÿ=ÕÅBuilding–™™a“Graphical“Obser•Û$v“er‘™™SwarmŽŸý‹¿With–?ýthe“model“swarm“defined,“arranging“for“a“graphical“observer“Swarm“is“the“next“step.‘ úForŽ¦Heatbugs,–?ýthe“code“is“in“HeatbugObserverSwarm.‘ úThe“structure“of“an“observer“swarm“is“almostŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ì« “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿exactly–?ýlike“building“a“model“swarm.Žºâ© Ü»ïhtml:ï html:Ÿ ßâ‘0Â@interface–ffHeatbugObserverSwarm“:“GUISwarm“ÇfŽ¤Æ‘5ffÂint–ffdisplayFrequency;“//“one“parameter:“update“freqŽ¡¡‘5ffid–ffdisplayActions;“//“schedule“data“structsŽ¡‘5ffid‘ffdisplaySchedule;Ž¡¡‘5ffHeatbugModelSwarm–ff*“heatbugModelSwarm;“//“the“Swarm“we're“observingŽ¡¡‘5ff//–ffLots“of“display“objects.“First,“widgetsŽ¡‘5ffXColormap–ff*“colormap;“//“allocate“coloursŽ¡‘5ffZoomRaster–ff*“worldRaster;“//“2d“display“widgetŽ¡‘5ffEZGraph–ff*“unhappyGraph;“//“graphing“widgetŽ¡¡‘5ff//–ffNow,“higher“order“display“and“data“objectsŽ¡‘5ffValue2dDisplay–ff*“heatDisplay;“//“display“the“heatŽ¡‘5ffObject2dDisplay–ff*“heatbugDisplay;“//“display“the“heatbugsŽ¡‘0ÇgŽŸ`t¿Again–?ýwe“have“input“parameters“(display“frequency),“schedule“data“structures,“and“residentŽ¤G®objects–?ý(model“swarm,“display“widgets).‘ úThe“important“exception“is“that“HeatbugObserverSwarmŽ¡is–?ýa“subclass“not“just“of“the“generic“Swarm“class,“but“specifically“a“GUISwarm.‘ úThat“impliesŽ¡that–?ýthe“HeatbugObserverSwarm“will“contain“a“control“panel“to“allow“the“user“to“stop“execution,Ž¡and–?ýwill“also“have“a“special“ïhtml:ï html:Âgo“¿method“to“set“everything“running.ŽŸŸJïhtml:ï html:Ÿ'ÅBuilding–™™a“Data“GraphŽŸ¼¿An–?ýexample“of“an“object“inside“the“HeatbugObserverSwarm“is“a“data“graph,“the“graph“of“averageŽŸunhappiness.‘ úHere–?ýis“the“code“necessary“to“create“that“object:Ž¦ïhtml:ï html:© ßâ‘0Â//–ffCreate“the“graph“widget“to“display“unhappiness.Ž¤Æ‘0unhappyGraph–ff=“[EZGraph“createBegin:“[self“getZone]];Ž¡‘0[unhappyGraph–ffsetTitle:“"Unhappiness“of“bugs“vs.“time"];Ž¡‘0[unhappyGraph–ffsetAxisLabelsX:“"time"“Y:“"unhappiness"];Ž¡‘0unhappyGraph–ff=“[unhappyGraph“createEnd]“;Ž¡¡‘0[unhappyGraph–ffcreateAverageSequence:“"unhappiness"Ž¡‘5ffwithFeedFrom:–ff[heatbugModelSwarm“getHeatbugList]Ž¡‘5ffandSelector:–ffM(getUnhappiness)]“;Ž¡¿The–?ýfirst“step“is“to“build“an“instance“of“an“EZGraph“and“set“its“captions.‘ úThen“a“SequenceŽ¤is–?ýcreated“inside“that“graph“(in“this“case,“an“AverageSequence).‘ úIn“general,“the“SequenceŽ¡requires–?ýa“target“object“and“a“message“with“which“to“extract“data“from“that“object“--“the“dataŽ¡is–?ýthen“plotted“as“one“line“in“the“graph.ŽŸ8äïhtml:ï html:¦‘0In–?ýthe“case“of“an“AverageSequence,“an“entire“collection“of“objects“is“presented“toŽ¡‘0it.‘ úThe–?ýAverageSequence“then“extracts“data“from“all“the“objects“in“the“collectionŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Øí “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿(in–?ýthis“case“a“List)“using“the“provided“message“(in“this“case“ïhtml:ï html:ÂgetUnhappiness¿),“andŽ¤‘/ºâgenerate–?ýa“datapoint“from“these“values“by“averaging“them.ŽºâŸŸJïhtml:ï html:Ÿ¿Åmain()ŽŸT¿The–?ýlast“main“type“of“code“needed“for“an“application“is“the“function“main(),“the“first“functionŽ¡called–?ýin“your“program.‘ úAll“the“real“work“has“been“done“already“-“all“that's“left“is“to“createŽ¡the–?ýobjects“at“the“right“time.ŽŸ Ü»ïhtml:ï html:Ÿ w`‘0ÂintŽ¤°D‘0main(int–ffargc,“char“**“argv)“ÇfŽ¡‘5ffÂid–fftheTopLevelSwarm“;Ž¡¡‘5ff//–ffSwarm“initialization:“all“Swarm“apps“must“call“this“first.Ž¡‘5ffinitSwarm(argc,‘ffargv);Ž¡¡‘5ff//–ffswarmGUIMode“is“set“in“initSwarm().“It's“set“to“be“1“if“youŽ¡‘5ff//–fftyped“heatbugs“-batchmode.“Otherwise,“it's“set“to“0.Ž¡¡‘5ffif–ff(swarmGUIMode“==“1)Ž¡‘5ff//–ffWe've“got“graphics,“so“make“a“full“ObserverSwarm“to“get“GUI“objectsŽ¡‘5fftheTopLevelSwarm–ff=“[HeatbugObserverSwarm“create:“globalZone];Ž¡‘5ffelseŽ¡‘5ff//–ffNo“graphics“-“make“a“batchmode“swarm“and“run“it.Ž¡‘5fftheTopLevelSwarm–ff=“[HeatbugBatchSwarm“create:“globalZone];Ž¡¡‘5ff[theTopLevelSwarm‘ffbuildObjects];Ž¡‘5ff[theTopLevelSwarm‘ffbuildActions];Ž¡‘5ff[theTopLevelSwarm–ffactivateIn:“nil];Ž¡‘5ff[theTopLevelSwarm‘ffgo];Ž¡¡‘5ff//–fftheTopLevelSwarm“has“finished“processing,“so“it's“time“to“quit.Ž¡‘5ffreturn‘ff0;Ž¡‘0ÇgŽ¡¿main()–?ýcalls“ïhtml:ï html:ÂinitSwarm“¿(required“in“all“Swarm“applications).‘ úIt“then“detects“if“it“shouldŽ¤do–?ýgraphics“or“not,“creates“the“appropriate“top“level“Swarm“to“contain“the“model,“and“setsŽ¡it–?ýto“running.‘ úSimple“as“that!ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿl®ÀConclusionŽŸy¿Swarm–?ýtries“to“help“computer“simulation“authors“by“making“it“easier“to“write“simulations“byŽ¡making–?ýit“more“formal.‘ úThe“text“above“gives“a“narrative“introduction“into“using“Swarm“forŽ¡your–?ýown“models,“but“a“real“understanding“of“Swarm“will“only“come“when“you“start“to“read“throughŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ãã “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿our–?ýexamples“and“try“to“write“your“own“applications.‘ úGood“luck,“and“may“your“simulations“beŽ¤ºâsuccessful!ŽºâŸ ^5ïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ìß “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Installing‘/SwarmŽ©Ö£¿Installing–?ýSwarm“will“take“some“time:‘ úvarious“external“libraries“need“to“be“acquired,“compiled,Ž¤and–?ýinstalled,“and“then“Swarm“itself“needs“to“be“compiled.‘ úPlease“report“any“problems“duringŽ¡installation–?ýback“so“that“we“can“try“to“fix“them“in“the“future.‘ úAlso“we've“tried“to“compileŽ¡some–?ýof“the“common“obstacles“to“installation“in“the“ïhtml:ï html:Swarm“FAQïhtml:ï html:Ž¦(faq/FAQ.html)Ž¤e|.ŽŸ ïhtml:ï html:Ÿïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Supported‘?ýSystemsïhtml:ï html:Ž¤8äïhtml:ï html:© ,˜‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Prerequisite‘?ýProgramsïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Prerequisite‘?ýLibrariesïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Configuring–?ýSwarm“Librariesïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Compiling–?ýSwarm“Librariesïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Compiling–?ýand“Running“Swarm“Applicationsïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Post-compile‘?ýcleanupïhtml:ï html:Ž©€’ïhtml:ï html:ŸéÀSupported‘QëSystemsŽŸÃ±¿Our–?ýintention“is“that“Swarm“will“run“on“any“modern“Unix“system.‘ úIdeally,“Swarm“itself“shouldŽ¤be–?ý100%“portable.‘ úSwarm“is“currently“known“to“be“running“on“SunOS“4.1.3,“Linux,“HP/UX,“someŽ¡SGI–?ýIrix“boxes,“MachTen/68k,“and“Solaris.‘ úSome“of“the“software“Swarm“uses“might“not“be“entirelyŽ¡portable;–?ýthese“problems“are“largely“out“of“our“hands.‘ úThe“major“difficulty“so“far“is“theŽ¡tricks–?ýthe“GNU“Objective“C“runtime“uses“may“not“work“properly“on“AIX“and“MachTen/PPC,“so“SwarmŽ¡may–?ýnot“work“on“those“systems.‘ úFixing“this“is“a“longterm“project;“if“you“absolutely“must“useŽ¡Swarm–?ýon“AIX“or“MachTen/PPC,“contact“us.ŽŸÁÂïhtml:ï html:Ÿï‘0See–?ýthe“ïhtml:ï html:Platform“Newsïhtml:ï html:Ž¤e|‘0(http://www.santafe.edu/projects/swarm/platforms.html)Ž¡‘0web–?ýpage“for“more“dynamic“information.Ž¦ïhtml:ï html:ŸéÀPr•°ger“equisite‘QëPr“ogramsŽ©Ã±¿We–?ýassume“you“already“have“Unix“and“X“Windows“on“your“system:‘ úthe“rest“of“this“software“isŽ¤freely–?ýavailable.› úExpect“to“spend“some“time“compiling“and“installing“these“packages.˜URLsŽ¡on–?ýthis“page“are“to“the“home“distribution“site:‘ úas“a“convenience,“the“Swarm“ftp“site“ïhtml:ï html:ftp://ftp.santafe.edu/pub/swarm/ïhtml:ï html:Ž¦(ftp://ftp.santafe.edu/pub/swarm/needed-software/)Ž¤e|contains–?ýcopies“of“the“necessary“packages“in“ïhtml:ï html:needed-software/ïhtml:ï html:Ž¡(ftp://ftp.santafe.edu/pub/swarm/needed-software/)Ž¡.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ïc “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ïhtml:ï html:Ÿ ‘:¿gcc‘?ý2.7.xŽŸ8äïhtml:ï html:© Ÿ‘Xgcc–?ýis“the“FSF's“C,“C++,“and“Objective“C“compiler.‘ úYou“need“gcc“2.7.2“orŽ¤‘Xgreater–?ýinstalled“on“your“system,“including“the“Objective“C“support,“libobjc.a.Ž¡‘XThe–?ýlatest“version“is“available“from“ïhtml:ï html:ftp://prep.ai.mit.edu/pub/gnu/ïhtml:ï html:Ž¤×û‘X(ftp://prep.ai.mit.edu/pub/gnu)Ž¡‘X.Žïhtml:ï html:ïhtml:ï html:¡‘XNote:‘ úSwarm–?ýwill“not“work“with“versions“of“gcc“before“2.7.2.ŽŸ8äïhtml:ï html:¦‘:GNU‘?ýmakeŽïhtml:ï html:¡‘XMake–?ýis“used“to“automate“building“programs:‘ úevery“OS“ships“their“own“versionŽ¤‘Xof–?ýmake“with“some“random“set“of“features.‘ úThe“Swarm“makefiles“currently“useŽ¡‘Xfeatures–?ýthat“are“not“supported“by“all“makes:‘ úGNU“make“is“the“only“one“guaranteedŽ¡‘Xto–?ýwork.› úLinux“systems“probably“use“GNU“make“already.˜The“latest“versionŽ¡‘Xof–?ýGNU“make“should“be“available“on“ïhtml:ï html:ftp://prep.ai.mit.edu/pub/gnu/ïhtml:ï html:ŽŸ×û‘X(ftp://prep.ai.mit.edu/pub/gnu/)ŽŸ8äïhtml:ï html:¦‘:gdbŽŸ8äïhtml:ï html:¦‘Xgdb–?ýis“the“GNU“debugger:‘ úSwarm“doesn't“require“this,“but“you“will“probablyŽ¡‘Xwant–?ýgdb“on“your“system“to“ïhtml:ï html:debug“programsïhtml:ï html:Ž¤×û‘X(debugging.html)Ž¡‘X.‘ úGdb–?ýis“available“on“ïhtml:ï html:ftp://prep.ai.mit.edu/pub/gnu/ïhtml:ï html:Ž¡‘X(ftp://prep.ai.mit.edu/pub/gnu/)Ž¡‘X.ŽŸG®ïhtml:ï html:Ÿ”eÀPr•°ger“equisite‘QëLibrariesŽŸ60¿Swarm–?ýuses“a“variety“of“freely“available“software“libraries.‘ úAll“of“these“libraries“need“toŽ¤be–?ýconfigured“and“installed“independently“of“Swarm.‘ úWhen“you“have“installed“them“all,“modifyŽ¡ïhtml:ï html:ÂMakefile.conf–?ý¿in“the“Swarm“library“package“to“tell“the“compiler“and“linker“where“to“find“them.Ž¡Note:‘ úit–?ýpays“to“spend“the“extra“time“to“build“shared“library“versions“of“these“things.ŽŸ—ïhtml:ï html:Ÿïhtml:ï html:¦‘:libXpmŽŸ8äïhtml:ï html:¦‘XlibXpm–?ýadds“pixmap“(coloured“bitmap)“support“to“X11.‘ úlibXpm“is“a“common“XŽ¡‘Xlibrary,–?ýmany“systems“already“have“it“installed.‘ úA“reasonably“modern“versionŽ¡‘Xis–?ýneeded:› úwe've“used“version“3.4f.˜If“you“get“complaints“about“"Object"Ž¡‘Xbeing–?ýmultiply“defined,“your“version“of“libXpm“is“too“old.‘ úThe“library“isŽ¡‘Xavailable–?ýfrom“ïhtml:ï html:ftp://ftp.x.org/contrib/libraries/xpm-3.4h.tar.gzïhtml:ï html:Ž¤×û‘X(ftp://ftp.x.org/contrib/libraries/xpm-3.4h.tar.gz)Ž¡‘X.Ž¤ïhtml:ï html:¡ïhtml:ï html:¤×û‘:Tcl/TkŽŸÕSïhtml:ï html:Ÿ¨‘XMore–?ýcommon“libraries:› úa“scripting“language“and“a“GUI“toolkit.˜These“librariesŽŸ‘Xare–?ýavailable“from“ïhtml:ï html:ftp://ftp.smli.com/pub/tcl/ïhtml:ï html:Ž¡‘X(ftp://ftp.smli.com/pub/tcl/)Ž¡‘Xor–?ýfrom“ïhtml:ï html:http://www.tcltk.comïhtml:ï html:Ž¡‘X(http://www.tcltk.com)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ý„ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Wºâ¿.› úSwarm–?ýworks“with“Tcl/Tk“versions“7.4/4.0,“7.5/4.1,“and“7.6/4.2.˜It“mayŽ¤‘Wºâwork–?ýwith“later“versions,“but“it“hasn't“been“tested.ŽºâŸcïhtml:ï html:Ÿïhtml:ï html:Ÿhœ‘:BLT-2.3Žïhtml:ï html:©Ì)‘XBLT–?ýis“an“add-on“to“Tk“that“provides“more“widgets.‘ úBLT“is“available“fromŽ¡‘Xïhtml:ï html:http://www.tcltk.com/blt/index.htmlïhtml:ï html:Ž¦‘X(http://www.tcltk.com/blt/index.html)Ž¦‘Xor‘?ýïhtml:ï html:ftp://ftp.neosoft.com/pub/tcl/sorted/devel/ïhtml:ï html:Ž¦‘X(ftp://ftp.neosoft.com/pub/tcl/sorted/devel/)Ž¦‘X.‘ úNote–?ýthat“BLT“2.3“works“with“either“Tcl/Tk“7.5/4.1“or“7.6/4.2,“whereasŽ¡‘XBLT–?ý2.1“only“works“with“versions“up“to“and“including“Tcl/Tk“7.5/4.1.‘ úThereŽ¡‘Xare–?ýproblems“with“using“BLT“2.3“in“that“some“of“the“functionality“has“changedŽ¡‘Xand–?ýnon-fatal“errors“may“spit“out“on“the“terminal“window“you“start“Swarm“in.Ž¡‘XBut,–?ýwe“haven't“taken“the“time“to“debug“these“things.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¤ “E‘:tclobjc-1.2ŽŸ8äïhtml:ï html:¡‘XGlue–?ýbetween“TCL“and“Objective“C.“This“version“of“the“library“is“currentlyŽ¤‘Xonly–?ýavailable“from“the“Swarm“authors,“and“is“ïhtml:ï html:distributedïhtml:ï html:Ž¦‘X(http://www.santafe.edu/projects/swarm/release.html)Ž¦‘Xin–?ýthe“same“place“as“Swarm.ŽŸ€’ïhtml:ï html:ŸO¯ÀConguring–QëSwarm“LibrariesŽ©*^¿Once–?ýyou“have“all“of“the“above“software“installed,“the“next“step“is“to“configure“Swarm.‘ úFirstŽ¡unpack–?ýthe“Swarm“.tar.gz“file“into“a“convenient“place“ïhtml:ï html:Â(via–ffgzip“-dc“swarm-xx.yy.zz.tar.gzŽ¡|–fftar“xf“-)¿.ŽŸž5ïhtml:ï html:Ÿ Œ)‘0All–?ýconfiguration“of“Swarm“compilation“is“localized“to“the“file“ïhtml:ï html:ÂMakefile.conf¿.‘ úYouŽ¡‘0should–?ýchange“the“lines“OTHERINCDIRS“and“OTHERLIBDIRS“to“point“to“the“directoriesŽ¡‘0where–?ýthe“libraries“you“installed“are,“and“set“OTHERLIBS“to“link“in“other“OS-dependentŽ¡‘0libraries–?ýthat“might“be“required“on“your“system.‘ úIn“addition,“if“your“OS“doesn'tŽ¡‘0have–?ýïhtml:ï html:Âranlib¿,“then“configure“the“ïhtml:ï html:ÂRANLIB=“¿line“to“just“execute“ïhtml:ï html:Â/bin/true¿.ŽŸ8äïhtml:ï html:Ÿ “E‘0All–?ýof“the“procedures“run“by“make“are“defined“in“the“three“top“level“makefiles“ïhtml:ï html:ÂMake-Ž¡‘0file.conf¿,–?ýïhtml:ï html:ÂMakefile.lib¿,“and“ïhtml:ï html:ÂMakefile.appl¿.‘ úIf“you“run“into“problems,“you“mightŽ¡‘0need–?ýto“look“at“the“Makefile“code“in“there.ŽŸG®ïhtml:ï html:Ÿˆ“ÀCompiling–QëSwarm“Libraries“{“(not“r•°gequir“ed–Qëf‘hor“binaryŽŸ¼jdistrib§Œutions)Ž¦¿You've–?ýdone“the“hard“part,“now“type“"make"“and“watch“the“fun!‘ úMake“will“recursively“run“makeŽ¡in–?ýsubdirectories,“building“libraries,“installing“header“files“in“ïhtml:ï html:Âinclude“¿and“libraries“inŽ¡ïhtml:ï html:Âlib¿.‘ úIf–?ýrunning“"make"“in“the“root“Swarm“directory“does“nothing,“you“probably“aren't“runningŽ¡GNU‘?ýMake.ŽŸ ^5ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹™ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿Swarm–?ýis“set“up“so“that“you“can“run“make“in“subdirectories“and“expect“it“to“work.Ž¤‘/ºâIf–?ýa“particular“directory“doesn't“seem“to“make“correctly,“try“to“cd“into“that“directoryŽ¡‘/ºâand–?ýrun“"make"“from“there“to“better“see“what“the“problem“is.Žºâ©€’ïhtml:ï html:Ÿƒ†ÀCompiling–Qëand“Running“Swarm“A‘hpplicationsŽŸ^5¿Swarm–?ýapplications“are“distributed“separately:‘ úyou“will“need“to“download“and“unpack“applicationsŽ¡independently.‘ úAfter–?ýthe“application“is“unpacked,“you“will“have“to“change“the“ïhtml:ï html:ÂSWARMHOME“¿variableŽ¡in–?ýthe“Makefile.‘ úIt“is“setup,“by“default“to“point“to“"../swarm",“as“if“the“Swarm“librariesŽ¡were–?ýin“a“sibling“directory“called“"swarm".‘ úJust“edit“that“string“to“point“to“where“you“installedŽ¡the–?ýSwarm“libraries.› úNo“other“configuration“should“be“necessary.˜All“you“need“to“do“to“compileŽ¡an–?ýapplication“is“type“"make",“and“it“will“compile“and“link.ŽŸ—ïhtml:ï html:Ÿ Ç‘0Once–?ýthe“application“is“compiled,“just“run“it“out“of“its“own“directory.‘ úA“controlŽ¡‘0panel–?ýand“a“couple“of“parameter“windows“should“pop“up;“press“the“"Go"“button“to“watchŽ¡‘0it‘?ýrun.‘ úCongratulations!Ž¦ïhtml:ï html:Ÿƒ†ÀP§Œost-compile‘QëcleanupŽŸ^5¿After–?ýyou've“tried“out“the“Swarm“libraries“for“awhile“you“may“want“to“clean“up“the“intermediateŽ¡.o–?ýfiles.‘ úSwarm“is“set“up“so“that“the“only“files“that“you“need“after“compile“are“ïhtml:ï html:Â$(SWARMHOME)/Makefile.appl¿,Ž¡ïhtml:ï html:Â$(SWARMHOME)/Makefile.lib¿,–?ýïhtml:ï html:Â$(SWARMHOME)/Makefile.conf¿,“and“the“contents“of“ïhtml:ï html:Â$(SWARMHOME)/libŽ¡¿and–?ýïhtml:ï html:Â$(SWARMHOME)/include¿.‘ úIf“you“run“ïhtml:ï html:Âmake‘ffclean“¿in“ïhtml:ï html:Â$(SWARMHOME)¿,“it“will“throw“away“allŽ¡the–?ý.o“files“in“the“source“directories.‘ úYou“can“even“copy“out“the“Makefiles,“ïhtml:ï html:Âlib¿,“and“ïhtml:ï html:Âin-Ž¡clude–?ý¿to“someplace“else“on“your“system:› úno“paths“are“compiled“in.˜Just“remember“to“set“ïhtml:ï html:Â$(SWARMHOME)Ž¡¿to–?ýthe“right“directory“in“your“application's“makefile.‘ úIf“you“need“to“recompile“the“libraryŽ¡and–?ýwant“to“start“from“a“completely“clean“source“directory,“ïhtml:ï html:Âmake‘ffrealclean“¿will“delete“theŽ¡includes–?ýand“libs“created“or“copied“during“the“compile“process.‘ úNote“that“ïhtml:ï html:Âmake‘ffrealcleanŽ¡¿will–?ýdelete“*all*“the“files“in“the“include“and“lib“directories.‘ úSo,“if“you've“set“your“Makefile.confŽ¡to–?ýpoint“to“a“directory“where“you“have“other“include“files“and“libraries,“then“you“don't“wantŽ¡to–?ýdo“a“ïhtml:ï html:Âmake‘ffrealclean¿.ŽŸ zþïhtml:ï html:Ÿã7‘0For–?ýdebugging“purposes“it's“easiest“if“your“Swarm“libraries“are“compiled“with“ïhtml:ï html:ÂOPTFLAGS=-Ž¡‘0g–?ý¿and“you“leave“the“sources“around.‘ úHowever,“your“applications“will“run“faster“ifŽ¡‘0you–?ýcompile“with“optimization,“ïhtml:ï html:ÂOPTFLAGS=-O3‘ff-g¿.‘ úThis“will“make“debugging“insideŽ¡‘0the–?ýSwarm“libraries“strange,“but“gives“noticeable“performance“improvement.‘ úUsersŽ¡‘0of–?ýSparc“based“machines“should“also“see“the“notes“about“ïhtml:ï html:Â-mv8“¿in“ïhtml:ï html:ÂMakefile.conf¿.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹§ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Ov•Êìer“view–/of“the“Swarm“Distrib•ÜutionŽ¤•¿Swarm–?ýis“currently“in“beta“test“release.‘ úInstallation“directions“can“be“found“in“ïhtml:ï html:install.htmlïhtml:ï html:Ž¡(install.html)Ž©$X.› úDocumentation–?ýis“incomplete:˜learning“to“program“with“Swarm“will“require“reading“exampleŽ¤applications–?ýand“looking“at“the“header“files“in“libraries.‘ úAll“existing“documentation“is“indexedŽ¡in‘?ýïhtml:ï html:index.htmlïhtml:ï html:Ž¦(index.html)Ž¦.ŽŸïhtml:ï html:¤G®ïhtml:ï html:ŸàÂÀLibrariesŽŸÊ;¿The–?ýmain“part“of“Swarm“is“a“set“of“libraries,“one“per“source“directory.‘ úBriefly,“the“directoryŽ¡organization–?ýis“as“follows:Ž¤ŸJïhtml:ï html:ïhtml:ï html:©3"ó0ˆÛ pcrb7tÉlib,–ffinclude,“binŽŸÝ¿Installed–?ýlibraries,“include“files,“and“helper“binaries.Ž¡ïhtml:ï html:ïhtml:ï html:¦ÉsrcŽŸÈ/¿Swarm–?ýlibrary“sources.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¤ ët‘:Âdefobjïhtml:ï html:Ž©$X‘:(src/defobj.html)ŽŸbÌïhtml:ï html:Ÿ ÁŒ‘X¿Support–?ýof“Swarm“style“Objective“C“programmingŽŸ8äïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¡‘:Âcollectionsïhtml:ï html:Ž¦‘:(src/collections.html)ŽŸýoïhtml:ï html:Ÿ&é‘X¿Collection–?ýlibrary“--“various“objects“that“"collect"“other“objectsŽŸ8äïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¡‘:Âactivityïhtml:ï html:Ž¦‘:(src/activity.html)ŽŸbÌïhtml:ï html:Ÿ ÁŒ‘X¿Schedule–?ýexecution“mechanism“--“the“"process"ŽŸ8äïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¡‘:Âobjectbaseïhtml:ï html:Ž¦‘:(src/objectbase.html)ŽŸbÌïhtml:ï html:Ÿ ÁŒ‘X¿Base–?ýclass“for“simulated“objects“--“the“"agents"ŽŸ8äïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¡‘:Âspaceïhtml:ï html:Ž¦‘:(src/space.html)ŽŸbÌïhtml:ï html:Ÿ ÁŒ‘X¿2d–?ýspatial“environment“libaryŽŸ8äïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¡‘:Ârandomïhtml:ï html:Ž¦‘:(src/random.html)ŽŸýoïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹)| “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Wºâ¿Random–?ýnumber“libraryŽºâ¤8äïhtml:ï html:ïhtml:ï html:ïhtml:ï html:© j‘:Âsimtoolsïhtml:ï html:ŽŸHN‘:(src/simtools.html)ŽŸýoïhtml:ï html:ŸJß‘X¿Collected–?ýbits“of“code“necessary“for“running“SwarmŽ¡ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¦‘:Âtkobjcïhtml:ï html:ŽŸHN‘:(src/tkobjc.html)ŽŸbÌïhtml:ï html:Ÿ å‚‘X¿Graphical–?ýInterface“libraryŽ¡ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¦‘:Âanalysisïhtml:ï html:ŽŸHN‘:(src/analysis.html)ŽŸbÌïhtml:ï html:Ÿ å‚‘X¿Various–?ýobjects“that“help“with“data“processingŽŸ€’ïhtml:ï html:ŸËÔÀA‘hpplicationsŽŸ¦ƒ¿In–?ýaddition,“there“is“a“set“of“sample“Swarm“applications“that“are“distributed“separately.‘ úApplicationsŽ¤are–?ýthe“best“current“roadmap“for“the“Swarm“code:‘ úmuch“of“what“is“possible“with“Swarm“is“demonstratedŽ¡in–?ýthe“sample“applications.‘ úThe“most“important“applications“are:ŽŸ—ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:¦‘:ÂtemplateŽŸbÌïhtml:ï html:Ÿ å‚‘X¿Template–?ýsimulation.‘ úThe“code“itself“here“is“trivial,“but“provides“a“niceŽ¡‘Xbase–?ýfor“new“Swarm“programmers“to“start“from.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:ÂheatbugsŽŸbÌïhtml:ï html:Ÿ å‚‘X¿Heatbugs,–?ýa“simple“complex“system.‘ úThe“code“here“is“thoroughly“commentedŽ¡‘Xfor–?ýuse“as“a“guide“to“swarm“programming.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:ÂmousetrapŽŸbÌïhtml:ï html:Ÿ å‚‘X¿Mousetrap–?ýis“a“discrete“event“simulation“of“a“room“full“of“mousetraps“loadedŽ¡‘Xwith–?ýping-pong“balls.‘ úThe“triggering“of“one“of“the“traps“sets“off“a“chainŽ¡‘Xreaction–?ýsupposedly“similar“to“fission.‘ úIt“is“also“thoroughly“commented.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:ÂmarketŽžÉïhtml:ï html:Ÿ+…‘X¿Market–?ýis“an“Objective-C“wrapped“piece“of“legacy“code“originally“written“inŽ¡‘XC.–?ýIt“is“a“useful“example“of“how“to“convert“legacy“code“into“Swarm;“but,“itŽ¡‘Xis–?ýnot“very“instructive“on“Swarm“programming“in“general.ŽŸ€’ïhtml:ï html:ŸËÔÀCr°geditsŽ©¦ƒ¿The–?ýSwarm“developers“are“Roger“Burkhart“,“Glen“Ropella“,Ž¡Marcus–?ýDaniels“,“and“Alex“Lancaster““under“the“directionŽ¡of–?ýChris“Langton“.‘ úBut“credit“for“the“package“is“spread“out“over“many“people.Ž¡The–?ýSwarm“developers“can“be“reached“collectively“as“.‘ úMore“informationŽ¡is–?ýavailable“on“our“Web“page,“ïhtml:ï html:http://www.santafe.edu/projects/swarm/ïhtml:ï html:Ž¦(http://www.santafe.edu/projects/swarm/)ŽŸHN.ŽŸïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹4¢ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Aª “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Swarm–/T‘þªodo/W |ish“listŽŸq'¿Swarm–?ýis“an“open“ended“system“which“is“meant“to“grow“in“response“to“the“requirements“of“theŽ¤user–?ýbase,“either“by“inhouse“development“or“through“user“re-contributions.‘ úWe“are“thereforeŽ¡maintaining–?ýa“list“of“the“most“popular“requests“(both“in“terms“of“tools“and“libraries)“so“thatŽ¡groups–?ýof“users“can“recognize“common“requirements,“make“more“informed“suggestions“and“so“forth:ŽŸªïhtml:ï html:ŸG®ïhtml:ï html:ïhtml:ï html:©ƒ†ÀA–Që'Double'“SpaceŽŸ âcïhtml:ï html:ïhtml:ï html:Ÿ{Ò‘X¿Which–?ýcould“deal“with“notions“of“"distance"“and“answer“questions“of“the“form:Ž¡‘X"which–?ýother“objects“are“within“X“radius“of“me"?‘ úAn“initial“implementationŽ¡‘Xof–?ýsuch“a“space“has“been“re-contributed“by“ïhtml:ï html:Ginger“Boothïhtml:ï html:Ž¡‘X(http://peaplant.biology.yale.edu:8001/~ginger/)Ž¡‘Xand–?ýmay“serve“as“a“good“foundation“for“such“a“space.ŽŸ€’ïhtml:ï html:¦ÀComplete–QëBatch-Mode“SupportŽŸŸ¿Swarm–?ýcan“now“run“in“batch“mode,“which“should“allow“the“user“to“organize“large“parameter“sweepsŽ¤¼jover–?ýthe“models“s/he“is“implementing.‘ úHowever,“we“still“need“to“provide“adequate“and“standardizedŽ¡support–?ýfor“file“operations“(it“should“be“easy,“for“example,“to“load“the“parameters“of“an“experimentŽ¡from–?ýa“file).‘ úIn“order“to“do“this“we“will“provide“File“objects“which“will“allow“users“to“avoidŽ¡ad-hoc–?ýcoding“of“their“file-I/O.“This“support“will“be“in“place“well“before“V1.0.ŽŸ€’ïhtml:ï html:¦ÀMor°ge–QëAnalysis“T‘þioolsŽ¤^5¿The–?ýaverager“object“can“generate“the“Mean,“Max,“Min,“and“Count“of“a“given“input“stream.‘ úWeŽ©would–?ýlike“to“add“similar“tools“to“calculate“entropies,“mutual“information“and“other“such“measures.Ž¡‘0„¤ŽŽŸ ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹CŠ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Deb•Üugging–/T |ips“f‘ÿ{Jor“SwarmŽŸIš¿Debugging–?ýsoftware“is“an“art,“perhaps“even“more“so“than“writing“the“software“itself.‘ úAll“softwareŽ¤we–?ýwrite“will“have“bugs:‘ úit“is“important“to“know“how“to“diagnose“a“bug“when“it“happens“andŽ¡how–?ýto“write“code“defensively“so“you“have“less“bugs“in“the“first“place.ŽŸªïhtml:ï html:ŸG®ïhtml:ï html:Ÿ[ùÀFinding‘Qëb§ŒugsŽŸ6¨¿Bugs–?ýcome“in“two“categories:› úthose“that“crash“your“program“and“those“that“don't.˜Bugs“thatŽ¡crash–?ýyour“program“are“friendlier“because“they're“obvious.‘ úBugs“that“you“don't“notice“areŽ¡much–?ýmore“dangerous:‘ úone“nagging“question“in“every“programmer's“mind“should“be“"is“the“programŽ¡doing–?ýwhat“I“think“it“is“doing?"ŽŸ—ïhtml:ï html:Ÿffïhtml:ï html:Ÿç=ÅgdbŽ©|J¿By–?ýfar“the“most“useful“tool“for“finding“bugs“is“a“good“debugger,“a“shell“you“can“run“a“programŽ¡under–?ýand“set“breakpoints,“inspect“the“values“of“variables,“etc.‘ úThe“best“free“debugger“forŽ¡Unix–?ýis“probably“gdb,“available“from“the“ïhtml:ï html:GNU“ftp“siteïhtml:ï html:Ž¦(ftp://prep.ai.mit.edu/pub/gnu/)Ž©Øs.‘ úgdb–?ýseems“unfriendly“and“confusing“at“first,“but“it“is“definitely“worth“your“time“to“learnŽ¡it.ŽŸïhtml:ï html:¦‘0The–?ýmost“important“gdb“commands“are“ïhtml:ï html:Âhelp¿:› úbrowse“online“help,“ïhtml:ï html:Âwhere¿:˜show“me“aŽ¡‘0stack–?ýtrace,“where“did“we“crash?,“ïhtml:ï html:Âlist¿:‘ úshow“me“the“source“code“where“we“are,“ïhtml:ï html:Âbreak¿,Ž¡‘0set–?ýa“breakpoint,“and“ïhtml:ï html:Âprint¿:› úshow“me“the“value“of“of“some“expression.˜If“your“programŽ¡‘0is–?ýcrashing“on“you,“run“it“under“gdb“and“look“at“the“stack“trace.‘ úIf“it“looks“toŽ¡‘0be–?ýbuggy“but“you“don't“know“where,“start“setting“breakpoints“and“see“when“things“goŽ¡‘0awry.ŽŸŸJïhtml:ï html:Ÿç=Ågdb–™™and“Objecti•Û$v“e‘™™CŽ¤|J¿Unfortunately,–?ýat“this“time“gdb“does“not“directly“support“Objective“C.“There“are“ïhtml:ï html:some“workaroundsïhtml:ï html:Ž¡(http://www.cons.org/cracauer/objc-hint-gdb.html)Ž¦that–?ýmake“debugging“Objective“C“programs“possible.‘ úThey“are“based“on“the“knowledge“that“ObjectiveŽ©C–?ýis“little“more“than“a“glorified“syntax“for“structs“(objects)“and“strange“function“names“(methods).ŽŸ8äïhtml:ï html:Ÿffïhtml:ï html:Ÿç=Ådef£×obj:‘vÆxprint(),–™™xprintid(),“xfprint(),“xfprintid(),“xexec(),“and“xfexec()Ž¡¿Swarm–?ýalso“has“a“few“functions“defined“that“can“be“used“to“make“debugging“easier.‘ úIn“particular,Ž¦the–?ýfunction“xprint(object)“prints“out“the“class“of“an“object,“and“xexec(object,“"message")Ž¦calls–?ýthe“message“specified“on“the“object.‘ úThese“can“be“invoked“under“gdb“as“ïhtml:ï html:Âcall‘ffxprint(aHeatbug)¿.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Lû “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿Note–?ýthat“you“can't“pass“arguments“to“a“message,“nor“can“you“see“the“return“value.‘ úThere“areŽ¤ºâalso–?ýmethods“xfprint(collection)“and“xfexec(collection,“"message")“that“print“or“exec“foreachŽ¡ºâmember–?ýof“a“collection.ŽºâŸ£×ïhtml:ï html:ŸG®ïhtml:ï html:Ÿ mÀPr°ge½°vÓÅenting‘QëBugsŽŸÂ8¿Defensive–?ýprogramming“can“help“prevent“a“good“number“of“bugs.‘ úWhen“writing“code,“try“to“testŽ¡it–?ýincrementally:‘ úmake“small“changes“whose“effects“you“think“you“can“predict“and“then“testŽ¡them.› úDon't–?ýoutsmart“yourself“with“cleverness:˜write“code“correctly“first,“then“go“in“andŽ¡hack–?ýit“up“if“you“need“it“to“be“more“efficient.‘ úPut“in“sanity“checks“for“conditions“that“shouldn'tŽ¡go–?ýwrong“in“normal“usage,“but“might“if“you“make“a“mistake.ŽŸ—ïhtml:ï html:©ffïhtml:ï html:ŸrÍÅ-W‘ÿkallŽŸÚ¿Swarm–?ýcurrently“compiles“all“code“with“"gcc“-Wall",“which“tells“gcc“to“emit“warnings“for“aŽ¡lot–?ýof“things“that“it“wouldn't“normally“complain“about.‘ úWarnings“are“not“(necessarily)“errorsŽ¡-–?ýwarnings“will“be“generated“for“legal“code“if“gcc“thinks“that“what“you're“doing“could“easilyŽ¡be–?ýa“mistake.‘ úYou“might“find“this“frustrating“at“first,“but“it“helps“catch“a“lot“of“commonŽ¡errors,–?ýincluding“forgetting“to“include“a“prototype“or“forgetting“to“return“a“value“from“aŽ¡function.‘ úPassing–?ý-Wall“is“good“discipline.ŽŸ Ü»ïhtml:ï html:¦ïhtml:ï html:ŸrÍÅnil_methodŽŸÚ¿Objects–?ýin“Objective“C“are“essentially“pointers“to“structs.‘ úSo“what“happens“if“you“send“anŽ¡object–?ýto“the“pointer“0x0,“"nil"“in“Objective“C“parlance?‘ úUnfortunately,“most“implementationsŽ¡of–?ýObjective“C,“including“gcc,“define“methods“to“nil“as“having“no“effect.‘ úThe“codeŽŸ Ü»ïhtml:ï html:© +‘0ÂaHeatbug–ff=“[Heatbug“create:“aZone];Ž¤d‘5ffaHeatbug–ff=“0;“//“oops!“bug.Ž¡‘5ff[aHeatbug–ffsetIdealTemperature:“idealTemp];Ž¡¿will–?ýïhtml:ï html:not“generate“any“errors.ŽŸ8äïhtml:ï html:¦‘0The–?ýreason“this“is“unfortunate“is“that“it's“a“common“bug“to“trash“a“pointer“accidentally,Ž¤‘0set–?ýit“to“0.‘ úIt“would“be“nice“if“your“program“then“crashed“when“you“tried“to“sendŽ¡‘0a–?ýmessage“to“that“mangled“object:‘ úinstead,“the“message“send“will“fail“silently“andŽ¡‘0the–?ýprogram“will“continue“to“execute.‘ úThis“can“make“it“hard“to“find“bugs.ŽŸ8äïhtml:ï html:¦‘0There–?ýare“two“ways“to“make“messages“sent“to“nil“crash“your“program.‘ úThe“simplestŽ¡‘0is–?ýto“put“a“breakpoint“on“ïhtml:ï html:Ânil_method“¿under“gdb:‘ únil_method“is“invoked“every“timeŽ¡‘0a–?ýmessage“is“sent“to“nil.‘ úAlternately,“you“can“make“a“copy“of“the“libobjc“runtimeŽ¡‘0source–?ýand“edit“nil_method“to“do“whatever“you“want.‘ úThe“source“code“in“ïhtml:ï html:Âsrc/defobjŽ¡‘0¿contains–?ýa“file“ïhtml:ï html:Âobjc.patch“¿that“patches“the“runtime“from“gcc“2.7.2.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Y« “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:ŽŸ‘/ºâ(mailto:mgd@santafe.edu)ŽºâŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹fÓ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Emacs–/and“Objecti•Êìv“e‘/CŽŸu¿Emacs–?ýis“the“world's“best“editor,“infinitely“configurable“and“powerful“and“free.‘ úIf“you'reŽ¤not–?ýused“to“a“Unix“text“editor“and“want“to“write“programs,“emacs“is“probably“best“to“learn.Ž¡The–?ýinformation“here“will“show“you“how“to“set“up“emacs“to“use“an“Objective“C“specific“modeŽ¡for–?ýediting“source“code“and“how“to“get“emacs“to“colour“your“source“code“for“you“nicely.‘ úEmacsŽ¡can–?ýalso“help“you“find“compilation“errors,“run“a“debugger,“and“even“act“like“a“class“browser.Ž¡Docs–?ýfor“those“things“are“not“here,“see“the“Emacs“documentation“itself.ŽŸªïhtml:ï html:ŸG®ïhtml:ï html:Ÿ‡|Àobjc-modeŽ©b+¿One–?ýof“the“best“things“about“emacs“is“that“one“can“load“different“"major“modes"“to“edit“typesŽ¡of–?ýfiles.‘ úMajor“modes“making“editing“files“easier“by“providing“structure“to“your“editing.Ž¡In–?ýparticular,“there“are“programming“language“modes“that“do“nice“things“like“indentation“forŽ¡you.ŽŸ—ïhtml:ï html:Ÿ Ë‘0Starting–?ýwith“emacs-19.30,“the“default“C“mode“is“cc-mode.el,“a“nice“rewrite“of“theŽ¡‘0original–?ýc-mode.el.› úLuckily“for“us,“cc-mode.el“supports“Objective“C“directly.˜TheŽ¡‘0basic–?ýfunction“to“invoke“it“is“ïhtml:ï html:Âobjc-mode¿.‘ úThe“following“bit“of“code“in“your“.emacsŽ¡‘0will–?ýcause“emacs“to“automatically“enter“objc-mode“on“all“files“that“end“in“ïhtml:ï html:Â.m“¿orŽ¡‘0ïhtml:ï html:Â.h¿:ŽŸÉïhtml:ï html:Ÿç-‘0Â(setq‘ffauto-mode-alistŽ¤ö‘Pfd(append–ff'(("\\.h$"“.“objc-mode)Ž¡’†f`("\\.m$"–ff.“objc-mode))))ŽŸªzïhtml:ï html:Ÿ]”Àhilit19Ž¦¿Emacs–?ýrunning“under“X“has“the“ability“to“colour“your“source“code“according“to“syntax.‘ úThereŽ¤are–?ýtwo“packages“to“do“this:› úfont-lock“and“hilit19.˜I'm“told“font-lock“is“better,“but“I“stillŽ¡use–?ýhilit19.‘ úOnce“you“have“hilit19“running“in“your“emacs,“you“need“to“teach“it“how“to“highlightŽ¡Objective–?ýC“code.‘ úHere's“what“I“use“(cut“and“paste)ŽŸ—ïhtml:ï html:Ÿ Ë‘0Â;;–ffmodified“objective“c“-“get“defuns,“id.Ž¤ö‘:ÌÌ(let–ff((comments‘ÿþ'(("/\\*"“"\\*/"“comment)))Ž¡‘0(c++-comments–ff'(("//.*$"“nil“comment)Ž¡‘0("^/.*$"–ffnil“comment)))Ž¡‘0(strings‘ fd'((hilit-string-find–ff?'“string)))Ž¡‘0(preprocessor–ff'(("^#[“\t]*\$undef\\|define\$.*$"“"[^\\]$"“define)Ž¡‘0("^#.*$"–ffnil“include))))Ž¡¡‘E™˜(hilit-set-mode-patternsŽ¡‘Jÿþ'(objc-mode‘ffobjective-C-mode)Ž¡‘Jÿþ(appendŽ¡‘Pfdcomments–ffc++-comments“strings“preprocessorŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ h~ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘P!FÂ'(Ž¤‘/ºâ;;–fffunction“decls“are“expected“to“have“types“on“the“previous“lineŽ¡‘/ºâ("^\$\\(\\w\\|[$_]\$+::\\)?\$\\w\\|[$_]\$+\\s–ff*\$\\(\\w\\|[$_]\$+\\s“*((\\|(\\)[^)]*)+"“nil“defun)Ž¡‘/ºâ("^\$\\(\\w\\|[$_]\$+[–ff\t]*::[“\t]*\\)?\$\\(\\w\\|[$_]\$+\\|operator.*\\)\\s“*\$\\(\\w\\|[$_]\$+\\s“*((\\|(\\)[^)]*)+"“nil“defun)Ž¡‘/ºâ;;–ffnelson“-“objective“c“style“defunsŽ¡‘/ºâ("^[-+].*ÇfÂ"–ffnil“defun)Ž¡¡‘/ºâ("^\$template\\|typedef\\|struct\\|union\\|class\\|enum\\|public\\|private\\|protected\$.*$"–ffnil“decl)Ž¡‘/ºâ;;–ffdatatype“--“black“magic“regular“expression“(nelson“-“add“id)Ž¡‘/ºâ("[–ff\n\t(ÇfÂ]\$\\(const\\|register\\|volatile\\|unsigned\\|extern\\|static\$\\s“+\\)*\$\\(\\w\\|[$_]\$+_t\\|float\\|double\\|void\\|char\\|short\\|int\\|unsigned\\|long\\|id\\|FILE\\|\$\\(struct\\|union\\|enum\\|class\$\$[“\t]+\\(\\w\\|[$_]\$*\\)\\)\\)\$\\s“+\\*+)?\\|[“\n\t;()]\$"“nil“type)Ž¡¡‘/ºâ;;–ffObjective“C“stuff:“^@[word]“gets“keyword“colouringŽ¡‘/ºâ("^@\\sw*"–ffnil“keyword)Ž¡‘/ºâ;;–ffkey“wordsŽ¡‘/ºâ("[^_]\\<\$return\\|goto\\|if\\|else\\|case\\|default\\|switch\\|break\\|continue\\|while\\|do\\|for\\|super\\|self\$\\>[^_]"Ž¡‘5!H1‘ffkeyword)))))ŽŸ‘/ºâ„¤ŽŽºâŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹!s¥ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj‘/LibraryŽŸq'‘0„¤ŽŽ¤ïhtml:ï html:Ÿ·æ‘0óÓßŒ˜ ptmb7tÊDocumentation–and“Implementation“StatusŽŸ‘0„¤ŽŽ©G®ïhtml:ï html:Ÿ êÀOv•ÓÅer“viewŽŸ¯µ¿The–?ýdefobj“library“supports“the“style“of“object-oriented“programming“that“is“used“throughoutŽ¡Swarm.‘ úIt–?ýdefines“a“specific“style“for“using“the“Objective“C“language“that“includes“its“ownŽ¡standard–?ýconventions“for“creating“objects“and“for“storage“allocation,“error“handling,“and“debuggingŽ¡support.ŽŸ—ïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:Ÿ êÀDocumentationŽ¤¯µ¿The–?ýdefobj“library“follows“the“Swarm“ïhtml:ï html:library“interface“conventionsïhtml:ï html:Ž¡(defobj/library.html)Ž¤Q€.‘ úIt–?ýhas“following“standard“sections“of“documentation:Ž©8äïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:Ÿ œ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Usage‘?ýGuideïhtml:ï html:Ž¡‘0(defobj/guide.html)Ž¦ïhtml:ï html:© œ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Advanced–?ýUsage“Guideïhtml:ï html:Ž¡‘0(defobj/adv.html)ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface‘?ýReferenceïhtml:ï html:Ž¡‘0(defobj/ref.html)ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Subclassing‘?ýReferenceïhtml:ï html:Ž¡‘0(defobj/subclass.html)ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface–?ýDesign“Notesïhtml:ï html:Ž¡‘0(defobj/design.html)ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Implementation‘?ýNotesïhtml:ï html:Ž¡‘0(defobj/impl.html)ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹"z8 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¾(mailto:mgd@santafe.edu)ŽºâŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹#„T “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Documentation“andŽŸâImplementation‘/StatusŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¿The–?ýcurrent“interfaces“defined“in“defobj“are“expected“to“remain“stable,“with“the“exceptionŽ¡‘0of–?ýthose“relating“to“package“structure“and“custom-generated“classes.‘ úThose“facilitiesŽ¡‘0are–?ýin“process“of“being“totally“replaced,“and“will“not“be“documented“further“untilŽ¡‘0that–?ýreplacement“is“complete.‘ úDetails“of“support“for“defining“a“customized“type“willŽ¡‘0also–?ýbe“provided“later.Ž©8äïhtml:ï html:Ÿ Ç‘0All–?ýthe“interfaces“defined“in“the“header“file“are“currently“implemented,“except“forŽ¡‘0the–?ývarious“types“of“zones“that“would“hold“all“allocated“storage“in“a“collection“ofŽ¡‘0local–?ýpages,“and“that“would“provide“automatic“reclaim“of“unused“storage.‘ úThe“currentŽ¡‘0zone–?ýimplementation“supports“all“defined“allocation“messages,“and“also“maintains“theŽ¡‘0population–?ýof“the“zone“that“consists“of“all“objects“created“directly“within“it.Ž¦ïhtml:ï html:Ÿ Ç‘0The–?ýUsage“Guide“section“is“only“a“start,“but“it“does“include“subsections“that“discussŽ¡‘0the–?ýstyle“of“Objective“C“programming“adopted“for“use“throughout“Swarm.‘ úThere“is“aŽ¡‘0full–?ýset“of“Interface“Reference“sections,“though“some“details“remain“to“be“filledŽ¡‘0in.ŽŸïhtml:ï html:¡‘0Throughout–?ýthe“documentation,“a“parenthesized“comment“that“starts“with“(..‘ úindicatesŽ¡‘0an–?ýeditorial“comment“on“the“current“status“of“implementation“or“documentation.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹$… “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Library–/Interface“Con‘ÿ+¶vÊìentionsŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ‘ÎÀOv•ÓÅer“viewŽ¤3™¿Some–?ýof“the“basic“Swarm“libraries“are“implemented“using“object“definition“conventions“establishedŽ©by–?ýthe“ïhtml:ï html:defobj“libraryïhtml:ï html:Ž¡(../defobj.html)Ž¤Õd.‘ úThis–?ýdocument“explains“how“to“read“and“interpret“the“header“files“and“interface“definitionsŽ¦published–?ýby“such“libraries.‘ úIt“also“explains“the“typical“structure“of“documentation“providedŽ¦for–?ýlibraries“that“follow“these“conventions.Ž©ïhtml:ï html:¡‘0These–?ýconventions“are“documented“under“the“following“subsections:ŽŸ8äïhtml:ï html:¦ïhtml:ï html:¤ œ€‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿library–?ýheader“fileïhtml:ï html:Ž©8äïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿object–?ýtype“definitionsïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿GridTurtle‘?ýexampleïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿global–?ýobject“symbolsïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿interface–?ýdesign“conventionsïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿documentation‘?ýstructureïhtml:ï html:ŽŸ‘0„¤ŽŽŸffïhtml:ï html:ŸÅLibrary–™™Header“FileŽŸy;¿For–?ýa“library“that“adopts“these“conventions,“a“library“is“not“merely“a“collection“of“sourceŽ¤files–?ýthat“are“compiled“into“a“library“archive“under“control“of“a“make“file.‘ úInstead,“ObjectiveŽ¡C–?ýsource“files“in“the“library“are“processed“in“a“special“way“to“publish“their“definitions“notŽ¡only–?ýas“header“files,“but“as“generated“objects“available“at“runtime“to“make“full“use“of“theŽ¡library.› úA–?ýlibrary“processed“in“this“way“is“referred“to“as“as“a“"package."“(Note:˜some“ofŽ¡the–?ýnewer“Swarm“libraries,“such“as“objectbase“and“random,“don't“undergo“this“special“processingŽ¡and–?ýyet“still“follow“all“the“library“interface“conventions“described“in“this“document.)ŽŸ Ü»ïhtml:ï html:Ÿ œ€‘0The‘?ýïhtml:ï html:defobjïhtml:ï html:Ž¤Õd‘0(../defobj.html)Ž¡‘0library–?ýdocuments“the“full“details“of“special“processing“performed“on“a“package.‘ úForŽ¤‘0simply–?ýusing“a“library,“the“key“fact“to“keep“in“mind“is“that“the“entire“public“interfaceŽ¡‘0to–?ýa“library“is“declared“in“the“one“header“file“having“the“same“name“as“the“packageŽ¡‘0itself,–?ýplus“a“trailing“.h“suffix.‘ úAdditionally,“the“header“file“of“a“library“normallyŽ¡‘0documents–?ýonly“its“public“interface,“in“a“way“that“is“completely“separated“from“theŽ¡‘0implementation–?ýof“the“objects“it“specifies.Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹%î “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿The–?ýseparation“of“implementation“means“that“a“library“publishes“its“interface“entirelyŽ¤‘/ºâwithout–?ýreference“to“any“Objective“C“classes“which“implement“its“objects.‘ úEven“thoughŽ¡‘/ºâclasses–?ýare“often“thought“of“as“separating“the“interface“of“an“object“from“its“implementation,Ž¡‘/ºâthis–?ýseparation“is“far“from“complete.‘ úNot“only“do“classes“typically“contain“manyŽ¡‘/ºâinternal–?ýmethods“not“intended“for“external“use,“but“they“also“define“a“particularŽ¡‘/ºâstorage–?ýformat“for“an“object“defined“as“instance“variables.Žºâ©8äïhtml:ï html:Ÿ (d‘0A–?ýlibrary“instead“publishes“its“interface“as“a“set“of“public“object“types.‘ úTheseŽ¡‘0object–?ýtypes“may“also“be“supplemented“by“global“object“constants“called“symbols.‘ úBothŽ¡‘0these–?ýkinds“of“definitions“normally“appear“only“in“the“header“file“of“a“library.‘ úTheŽ¡‘0remaining–?ýsource“files“in“a“library“normally“contain“the“classes“which“implement“theŽ¡‘0object‘?ýtypes.Ž¦ïhtml:ï html:Ÿ (d‘0In–?ýa“library,“the“files“which“implement“classes“(including“class“header“files),“needŽ¡‘0not–?ýever“be“referenced“simply“to“make“use“of“the“implemented“capabilities“of“the“libraryŽ¡‘0object–?ýtypes.‘ úDocumentation“for“the“library“is“normally“expressed“entirely“in“termsŽ¡‘0of–?ýthe“types“and“symbols“published“in“the“library“header“file.‘ úIf“a“feature“doesŽ¡‘0not–?ýappear“in“the“library“header“file,“it“should“not“be“considered“part“of“a“supportedŽ¡‘0public‘?ýinterface.Ž¦ïhtml:ï html:Ÿ (d‘0Individual–?ýclass“header“files“are“required“to“subclass“from“existing“implementations,Ž¡‘0but–?ýinterfaces“for“subclassing“are“an“entirely“separate“issue“from“normal“public“useŽ¡‘0of–?ýan“object“library.‘ úClass“inheritance“can“be“a“powerful“implementation“technique,Ž¡‘0but–?ýextension“of“an“existing“class“framework“is“typically“safe“only“if“performed“inŽ¡‘0explicitly–?ýpermitted“ways.‘ úIf“a“library“supports“subclassing“at“all,“it“must“carefullyŽ¡‘0state–?ýwhich“classes“may“be“subclassed“and“in“what“ways.‘ úFor“a“library“package,“thisŽ¡‘0information–?ýis“supplied“outside“the“library“header“file.‘ úThe“library“header“fileŽ¡‘0specifies–?ýonly“the“interfaces“by“which“objects“are“intended“to“be“used,“whether“implementedŽ¡‘0by–?ýa“local“class“or“an“external“subclass.Ž¦ïhtml:ï html:Ÿ (d‘0Remaining–?ýsections“of“this“document“explain“the“declarations“which“appear“in“a“libraryŽ¡‘0header–?ýfile,“and“end“with“a“suggested“structure“of“documentation“to“be“provided“forŽ¡‘0a–?ýlibrary.‘ úThe“libraries“of“Swarm“mostly“follow“this“structure.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ¨öÅObject–™™T‘þï5ype“DenitionsŽŸ¿The–?ýinterfaces“to“objects“defined“by“a“library“are“specified“by“object“type“definitions.‘ úAnŽ¡object–?ýtype“defines“only“a“set“of“messages“which“may“be“sent“to“an“object“over“various“phasesŽ¡of–?ýits“lifetime.‘ úAn“object“type“makes“no“commitment“to“the“classes“that“might“be“used“to“implementŽ¡the‘?ýobject.ŽŸ Ü»ïhtml:ï html:Ÿ (d‘0Multiple–?ýclasses“may“all“implement“the“same“messages“belonging“to“a“type.‘ úThe“independenceŽ¡‘0of–?ýtypes“and“classes“means“that“different“classes“can“provide“alternate“implementationsŽ¡‘0of–?ýthe“same“object“type.‘ úFor“example,“a“particular“implementing“class“might“be“selectedŽ¡‘0to–?ýoptimize“the“implementation“for“a“particular“case.Ž¦ïhtml:ï html:Ÿ (d‘0Object–?ýtypes“are“similar“to“protocols“defined“by“Objective“C,“and“the“declarationsŽ¡‘0appearing–?ýin“a“library“header“file“are“a“minor“adaptation“of“Objective“C“protocolŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹&›€ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿syntax.‘ úA–?ýkey“difference“from“protocols“is“that“object“types“are“published“as“realŽ¤‘/ºâexternal–?ýobjects“that“may“be“used“at“runtime“to“create“instances“of“a“type.‘ úA“futherŽ¡‘/ºâdifference–?ýis“that“the“object“types“of“the“defobj“library“are“divided“into“separateŽ¡‘/ºâinterfaces–?ýthat“define“distinct“phases“of“an“object's“life“cycle.ŽºâŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ{9ÅGridT‘þ¬áurtle‘™™exampleŽŸ×b¿An–?ýexample“will“help“illustrate“the“features“of“type“definitions“supported“by“the“defobj“library.Ž¡Throughout–?ýdocumentation“of“the“basic“Swarm“libraries,“a“series“of“running“examples“will“beŽ¡based–?ýon“a“simple“type“of“object“belonging“to“sample“Swarm“simulations.‘ úThis“type“of“objectŽ¡is–?ýan“agent“that“move“around“on“a“two-dimensional“grid,“always“moving“in“a“current“directionŽ¡that–?ýit“maintains“internally.‘ úThis“agent“is“like“a“"turtle"“of“the“original“Logo“system,“exceptŽ¡that–?ýits“position“is“constrained“to“discrete“integer“values“of“its“X-Y“coordinates,“and“itsŽ¡direction–?ýis“always“one“of“the“four“orthogonal“directions“north,“east,“south,“or“west.ŽŸ Ü»ïhtml:ï html:Ÿ ú§‘0Following–?ýis“a“complete“library“header“file“for“a“library“which“defines“such“an“object,Ž¡‘0called‘?ýGridTurtle:Ž¤ïhtml:ï html:¡ïhtml:ï html:¤3‹‘0Â/*Ž¡‘0Name:‘0™–GridTurtle.hŽ¡‘0Description:‘ ÌÌobject–fftype“for“Swarm“example“programsŽ¡‘0Library:‘ fdgridŽ¡‘0*/Ž¡¡‘0#import‘ffŽ¡¡‘0@deftype–ffGridTurtle“CREATINGŽ¡‘0-–ff(void)“setXLocMax:“(int)xLocMax;Ž¡‘0-–ff(void)“setYLocMax:“(int)yLocMax;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setXLoc:“(int)xLoc;Ž¡‘0-–ff(void)“setYLoc:“(int)yLoc;Ž¡‘0-–ff(void)“setXLoc:“xLoc“setYLoc:“yLoc;Ž¡¡‘0-–ff(void)“setDirection:“direction;Ž¡‘0USINGŽ¡‘0-–ff(int)“getXLoc;Ž¡‘0-–ff(int)“getYLoc;Ž¡¡‘0-‘ffgetDirection;Ž¡¡‘0-–ff(void)“move:“(int)distance;Ž¡‘0-–ff(void)“turn:“(int)angle;‘ ÌÌ//“angle“measured“in“units“of“pi/2“(90“deg.)Ž¡‘0-–ff(void)“print;Ž¡‘0@endŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹'ªü “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤‰Ù‘/ºâÂid–ff“North,“East,“South,“West;Ž¡¡‘/ºâ#import‘ff"grid.xt"Ž¡ºâ¿An–?ýobject“type“is“defined“by“an“@deftype“declaration.– ú(Note:“newer–?ýlibraries,“including“objectbaseŽ¤ºâand–?ýrandom,“now“follow“the“library“interface“conventions“without“using“this“special“@deftypeŽ¡ºâtag.‘ úInstead–?ýthey“use“just“an“ordinary“@protocol“declaration,“but“otherwise“they“follow“allŽ¡ºâthe–?ýstructure“explained“in“this“document.)‘ úThe“syntax“of“such“declaration“is“identical“toŽ¡ºâthat–?ýof“an“Objective“C“@protocol“definition,“except“for“the“entirely“uppercase“keywords“(CREATABLE,Ž¡ºâCREATING,–?ýSETTING,“USING)“appearing“in“the“GridTurtle“example“above.‘ úAll“these“modificationsŽ¡ºâof–?ýObjective“C“syntax“are“accomplished“by“simple“preprocessor“macros;“no“extensions“to“theŽ¡ºâlanguage–?ýcompiler“are“involved.Žºâ©8äïhtml:ï html:Ÿ Põ‘0When–?ýthis“library“header“file“is“processed“(by“a“special“rule“in“a“make“file),“anŽ¡‘0external–?ýobject“id“with“the“name“GridTurtle“is“automatically“published.‘ úThe“nameŽ¡‘0of–?ýa“defined“type“becomes“an“ordinary“object“that“accepts“specific“messages“definedŽ¡‘0by–?ýthe“defobj“library.‘ úThe“ïhtml:ï html:defobj“libraryïhtml:ï html:Ž¤‰Ù‘0(../defobj.html)Ž¡‘0explains–?ýthe“details“of“such“messages;“the“only“purpose“here“is“to“explain“the“basicŽ¤‘0sections–?ýof“a“deftype“declaration.Ž¦ïhtml:ï html:Ÿ Põ‘0deftype–?ýdeclarations“follow“the“syntax“as“Objective“C“protocols“for“inheriting“messagesŽ¡‘0from–?ýeach“other:‘ úa“list“of“names“enclosed“in“angle“brackets“(e.g.,“–?ýabove)“gives“the“names“of“other“declared“types“containing“messages“to“be“supportedŽ¡‘0by–?ýthe“new“type“as“well.‘ ú(These“types“referenced“here“are“defined“by“the“importedŽ¡‘0file–?ý.)‘ úLike“protocols,“full“multiple“inheritance“of“types“is“supported.Ž¡‘0The–?ýsame“messages“may“be“inherited“any“number“of“times“through“any“path“with“no“differentŽ¡‘0effect–?ýthan“if“inherited“or“declared“just“once,“so“long“as“no“conflicts“occur“in“anyŽ¡‘0of–?ýtheir“argument“or“return“types.Ž¦ïhtml:ï html:Ÿ Põ‘0The–?ýCREATABLE“tag“appearing“in“the“inherited“type“list“above“is“a“special“type“whichŽ¡‘0defines–?ýno“messages“of“its“own,“but“merely“marks“the“type“as“one“which“supports“directŽ¡‘0creation–?ýof“instances“of“the“type.‘ úWithout“this“tag,“the“only“role“of“a“type“is“toŽ¡‘0define–?ýmessages“for“inheritance“by“other“types.‘ úWith“this“tag,“the“global“type“objectŽ¡‘0has–?ýa“particular“implementation“that“supports“object“creation“using“standard“messagesŽ¡‘0defined–?ýin“defobj.Ž¦ïhtml:ï html:Ÿ Põ‘0The–?ýdeclared“messages“of“the“type“may“be“separated“into“sections“marked“by“the“specialŽ¡‘0uppercase–?ýtags“such“as“CREATING,“SETTING,“and“USING“above.‘ ú(Currently,“these“areŽ¡‘0the–?ýonly“such“tags“which“may“occur.)‘ úThese“sections“each“define“messages“belongingŽ¡‘0to–?ýa“particular“defined“"interface"“of“the“object“type,“which“are“further“combinedŽ¡‘0into–?ýdistinct“"phases"“of“an“object“lifecycle“supported“by“defobj“messages.‘ úFurtherŽ¡‘0explanation–?ýof“the“interfaces“and“phases“defined“by“this“example“are“provided“in“theŽ¡‘0ïhtml:ï html:Usage‘?ýGuideïhtml:ï html:Ž¤‰Ù‘0(guide.html)Ž¡‘0of–?ýthe“defobj“library.Ž¦ïhtml:ï html:Ÿ Põ‘0The–?ýfollowing“line“at“the“end“of“the““header“file“above“is“required“as“partŽ¤‘0of–?ýthe“standard“conventions“for“coding“a“library“header“file:‘ úThis“line“adds“no“informationŽ¡‘0to–?ýthe“header“file,“but“is“required“as“part“of“the“system“by“which“definitions“areŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹(´9 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿automatically‘?ýgenerated.Žºâ©8äïhtml:ï html:Ÿïhtml:ï html:¤ Ñ‘0Â#import‘ff"grid.xt"ŽŸbÌïhtml:ï html:Ÿ4‘0„¤ŽŽŸffïhtml:ï html:Ÿ‰cÅGlobal–™™Object“SymbolsŽŸåŒ¿The–?ý“header“file“above“also“contains“the“declaration:ŽŸ Ü»ïhtml:ï html:¡‘0Âid–ff‘ ÌÌNorth,“East,“South,“West;ŽŸAµ¿Lines–?ýthat“declare“global“id“variables“of“type“Symbol,“EventType,“Warning,“or“Error“(usingŽ¤the–?ýangle“bracket“syntax“of“id“variables“conforming“to“a“protocol)“are“processed“somewhat“likeŽ¡deftype–?ýdeclarations“in“that“they“also“produce“global“id“variables“initialized“to“support“particularŽ¡messages–?ýdefined“by“defobj.‘ úThese“global“variables,“however,“are“not“used“to“define“or“implementŽ¡other–?ýmessage“interfaces,“but“only“to“define“certain“fixed“capabilities“referenced“throughŽ¡their–?ýglobal“object“names.Ž¦ïhtml:ï html:Ÿ Ñ‘0If–?ýdeclared“as“a“Symbol,“as“in“the“case“here,“the“generated“objects“have“no“particularŽ¡‘0behavior–?ýof“their“own“(other“than“the“character“string“of“their“name),“but“only“serveŽ¡‘0to–?ýdefine“unique“global“id“constants“which“may“be“used“as“distinct“named“values“inŽ¡‘0messages.‘ úIn–?ýthis“example,“the“current“direction“of“a“GridTurtle“object“is“representedŽ¡‘0by–?ýone“of“the“symbol“names“North,“East,“South,“or“West.‘ úThese“values“are“like“theŽ¡‘0enum–?ýconstants“of“the“C“language,“except“that“they“are“defined“as“full“Objective“CŽ¡‘0objects,–?ýand“may“be“used“with“further“restrictions.‘ úAn“EventType,“or“a“Warning“orŽ¡‘0Error,–?ýdefines“a“further“subtype“of“a“Symbol“constant“with“further“specialized“messagesŽ¡‘0documented–?ýin“defobj.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ‰cÅInterface–™™Design“Con‘ÿl”vÛ$entionsŽŸåŒ¿A–?ývariety“of“rules“on“naming“and“declaration“of“object“types,“symbols,“and“messages“are“followedŽ¡by–?ýmany“of“the“Swarm“libraries.‘ úThese“rules“help“establish“a“basic“consistency“on“the“libraryŽ¡interfaces.‘ úFollowing–?ýis“a“list“of“such“conventions“that“apply“to“a“public“library“interface,Ž¡some–?ýbut“not“all“of“which“are“derived“from“standard“Smalltalk“or“Objective“C“coding“practice:ŽŸ Ü»ïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:Ÿ Ñ‘0ïcolor push BlackÁlï color popŽŽ‘:¿Names–?ýof“global“object“constants“are“capitalized.‘ úIn“the“public“interface,“suchŽ¡‘:names–?ýinclude“types“and“symbols.Ž¦ïhtml:ï html:Ÿ Ñ‘0ïcolor push BlackÁlï color popŽŽ‘:¿Recapitalization–?ýseparates“words“of“a“compound“name“(e.g.,“GridTurtle).‘ úUnderscoresŽ¡‘:are–?ýgenerally“not“used.Ž¦ïhtml:ï html:Ÿ Ñ‘0ïcolor push BlackÁlï color popŽŽ‘:¿Message–?ýnames“start“with“a“lower-case“character,“and“are“named“using“verbs.‘ úNounsŽ¡‘:that–?ýrepresent“gettable“or“settable“components“of“object“state“(e.g.,“DirectionŽ¡‘:of–?ýa“GridTurtle),“are“prefixed“by“get“or“set“to“indicate“the“action“being“performed.Ž¦ïhtml:ï html:Ÿ Ñ‘0ïcolor push BlackÁlï color popŽŽ‘:¿The–?ýSmalltalk“convention“that“a“message“return“the“receiver“of“a“message“if“thereŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹)Ãã “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘9ºâ¿is–?ýno“other“specific“return“value“is“generally“*not*“followed.‘ úIf“there“is“no“specificŽ¤‘9ºâreturn–?ývalue“needed“from“a“message“the“return“type“is“declared“(void).ŽŸ‘/ºâ„¤ŽŽºâŸffïhtml:ï html:Ÿ£×ÅDocumentation‘™™Structur½«eŽŸ¿The–?ýfollowing“standard“sections“of“documentation“are“suggested“for“libraries“that“follow“theŽ¡strict–?ýinterface“vs.‘ úimplementation“separation“of“library“packages,“each“with“purpose“andŽ¡typical–?ýcontents“as“given:ŽŸ Ü»ïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:¤ #E‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Usage‘?ýGuideŽ©8äïhtml:ï html:¡‘:Tutorial–?ýintroduction“to“a“library.‘ úFocuses“on“the“most“common“uses“in“an“orderŽ¤‘Hreflecting–?ýthe“needs“of“a“first-time“user.‘ úMost“explanation“by“means“of“progressivelyŽ¡‘Helaborated–?ýexamples.‘ úServes“as“a“guided“tour“of“major“library“capabilities.Ž¡‘HNo–?ýattempt“at“reference-style“completeness.Ž¦ïhtml:ï html:Ÿïhtml:ï html:¤ #E‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Advanced–?ýUsage“GuideŽ¦ïhtml:ï html:¡‘:Continues–?ýoverview“of“all“significant“capabilities“of“a“library,“including“thoseŽ¤‘Hwhich–?ýmight“be“needed“by“advanced“users“customizing“or“extending“built-in“capability.Ž¡‘HProvides–?ýexamples“of“specialized“uses“extending“beyond“normal,“basic“usage,“butŽ¡‘Hstill–?ýusing“built-in“features“of“the“library“framework.‘ úHelps“to“simplify“theŽ¡‘HUsage–?ýGuide“by“providing“a“location“for“overflow“of“more“advanced“features.Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ #E‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface‘?ýReferenceŽž¬ïhtml:ï html:Ÿ?}‘:Complete,–?ýconcise“summary“of“all“features“of“a“library.‘ úFills“the“role“a“Unix“"manŽ¡‘Hpage"–?ýin“providing“comprehensive“definition“of“library“services.‘ úLittle“or“noŽ¡‘Hconcern–?ýto“provide“path“of“tutorial“introduction.‘ úDoes“not“contain“extendedŽ¡‘Hexamples,–?ýat“most“only“fragments“of“examples“which“serve“needs“of“specification.Ž¦ïhtml:ï html:Ÿïhtml:ï html:¤ #E‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Subclassing‘?ýReferenceŽ¦ïhtml:ï html:¡‘:Documents–?ýthe“rules“for“writing“new“classes“which“subclass“from“classes“that“implementŽ¤‘Hthe–?ýlibrary.‘ úBecause“a“library“might“use“complex“combinations“of“classes“toŽ¡‘Himplement–?ýthe“range“of“behaviors“defined“by“its“types,“the“classes“in“a“libraryŽ¡‘Hare–?ýnot“automatically“usable“as“superclasses“of“user-defined“classes.‘ úEach“libraryŽ¡‘Hdocuments–?ýwhich“classes“are“available“for“use“as“superclasses,“and“the“specificŽ¡‘Hrules–?ýthat“must“be“followed“when“subclassing“from“these“classes.Ž¦ïhtml:ï html:Ÿïhtml:ï html:¤ #E‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface–?ýDesign“NotesŽ¦ïhtml:ï html:¡‘:Explains–?ýwhy“choices“were“made“the“way“they“were“in“the“design“of“the“public“interfaceŽ¤‘Hto–?ýa“library,“including“other“alternatives“considered.‘ úServes“as“a“"Rationale"Ž¡‘Hdocument–?ýfor“the“documented“interface.‘ úMay“include“historical“background“deliberatelyŽ¡‘Hleft–?ýout“of“the“preceding“sections.‘ úMay“also“include“references“to“other“work.Ž¦ïhtml:ï html:Ÿïhtml:ï html:¤ #E‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Implementation‘?ýNotesŽ¦ïhtml:ï html:¡‘:Explains–?ýthe“structure“of“classes“by“which“the“types“of“a“library“are“implemented.Ž¤‘HSummarizes–?ýthe“status“of“implementation“if“still“incomplete“and“lists“items“ofŽ¡‘Hpossible–?ýfuture“work.‘ úProvides“overview“and“high-level“structure“of“the“implementationŽ¡‘Hin–?ýwhatever“ways“would“best“guide“a“reader“of“implementation“source“code.‘ úMayŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹*Ñ³ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Gºâ¿also–?ýdiscuss“tradeoffs“considered“along“with“references“to“related“or“supportingŽ¤‘Gºâwork.Žºâïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹+âë “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Usage“GuideŽŸq'‘0„¤ŽŽŸ¼jïhtml:ï html:ŸüµContentsŽŸÃjïhtml:ï html:Ÿïhtml:ï html:ŸÈf‘0ïcolor push Black¿1.ï color popŽŽ‘<ïhtml:ï html:Why–?ýSwarm“uses“Objective“Cïhtml:ï html:Ž¤8äïhtml:ï html:© áÅ‘0ïcolor push Black2.ï color popŽŽ‘<ïhtml:ï html:Swarm–?ýstyle“of“Objective“C“programmingïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black3.ï color popŽŽ‘<ïhtml:ï html:Creating‘?ýobjectsïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black4.ï color popŽŽ‘<ïhtml:ï html:Storage‘?ýzonesïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black5.ï color popŽŽ‘<ïhtml:ï html:Standard–?ýobject“messagesïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black6.ï color popŽŽ‘<ïhtml:ï html:Debugging‘?ýsupportïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black7.ï color popŽŽ‘<ïhtml:ï html:Symbolsïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black8.ï color popŽŽ‘<ïhtml:ï html:Error‘?ýhandlingïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push Black9.ï color popŽŽ‘<ïhtml:ï html:Class‘?ýobjectsïhtml:ï html:ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ×ÀWh½°y–QëSwarm“uses“Objecti•ÓÅv“e‘QëCŽŸxÞ¿Swarm–?ýuses“object-oriented“programming“not“only“because“this“is“a“good“way“to“build“general-purposeŽ¤software–?ýlibraries,“but“because“the“very“concept“of“an“object“is“at“the“base“of“how“you“buildŽ¡a–?ýmodel“in“Swarm.‘ úTo“build“a“simulation“in“Swarm,“the“first“step“to“define“the“various“kindsŽ¡of–?ýobjects“that“can“inhabit“some“real“or“artificial“world,“and“the“second“step“is“to“defineŽ¡the–?ýkinds“of“events“that“can“occur“to“these“objects,“including“all“the“different“ways“thatŽ¡the–?ýobjects“can“interact“with“each“other.ŽŸ—ïhtml:ï html:¦‘0The–?ýbasic“concept“of“an“object“is“that“it“responds“to“external“events,“and“that“theŽ¡‘0only–?ýthing“that“really“matters“about“an“object“are“the“ways“it“can“be“observed“respondingŽ¡‘0to–?ýthese“events.‘ úIn“an“object-oriented“programming“system,“an“object“is“representedŽ¡‘0by–?ýsome“uniquely“identified“chunk“of“data,“and“the“events“are“the“dynamic“operationsŽ¡‘0that–?ýcan“be“made“to“occur“on“these“objects.ŽŸ8äïhtml:ï html:¦‘0Different–?ýobject-oriented“programming“systems“define“the“operations“that“occur“onŽ¡‘0objects–?ýin“different“ways.‘ úFor“example,“in“C++“the“operations“are“called“"memberŽ¡‘0functions"–?ýand“look“much“like“an“ordinary“function“call“in“the“C“language.‘ úIn“ObjectiveŽ¡‘0C,–?ýan“operation“on“an“object“is“called“a“"message"“and“has“a“special“syntax“by“whichŽ¡‘0you–?ýcall“it,“but“a“message“also“has“arguments“and“behaves“in“many“respects“like“aŽ¡‘0call–?ýto“a“function.ŽŸïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹,åX “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿The–?ýkey“requirement“for“Swarm“is“to“be“able“to“make“all“these“operations“happen“toŽ¤‘/ºâany–?ýobject“at“any“time,“whenever“they're“supposed“to“occur“within“some“simulated“world.Ž¡‘/ºâIt–?ýstores“these“operations“inside“its“own“data“structures,“and“when“you“run“a“simulationŽ¡‘/ºâin–?ýSwarm,“the“Swarm“system“itself“traverses“these“data“structures“to“make“the“necessaryŽ¡‘/ºâoperations–?ýhappen“at“the“proper“time.Žºâ©8äïhtml:ï html:Ÿ A‘0Swarm–?ýneeds“to“be“able“to“make“any“kind“of“action“happen“to“any“kind“of“object“atŽ¡‘0any–?ýtime,“and“to“do“this“it“needs“very“general-purpose“structures“that“hold“some“kindŽ¡‘0of–?ýrepresentation“of“the“actions“themselves.‘ úThat's“a“special“requirement“that“notŽ¡‘0every–?ýobject“language“provides.‘ úYou“already“have“enough“work“to“define“the“kindsŽ¡‘0of–?ýobjects“that“can“exist“inside“your“model,“and“Swarm“doesn't“want“you“to“have“toŽ¡‘0define–?ýan“even“larger“number“of“objects“for“every“kind“of“event“that“might“occur“toŽ¡‘0your–?ýobjects.‘ úInstead,“it“wants“the“object“language“to“provide“it“with“a“representationŽ¡‘0of–?ýthe“operations“on“objects“that“you've“already“defined.‘ úSwarm“can“then“store“theseŽ¡‘0representations–?ýin“its“own“data“structures,“and“make“the“operations“happen“wheneverŽ¡‘0it–?ýneeds“to.ŽŸïhtml:ï html:ŸI%‘0In–?ýSwarm,“the“representation“of“events“that“happen“on“objects“are“just“as“fundamentalŽ¡‘0to–?ýthe“model“as“the“objects“themselves.‘ úThat's“why“Swarm“is“a“"discrete-event"“simulationŽ¡‘0system.‘ úBut–?ýif“the“object“system“doesn't“provide“a“general-purpose“enough“representationŽ¡‘0of–?ýevents“as“well“as“objects,“there“would“be“a“lot“more“work“to“do.‘ úThe“ObjectiveŽ¡‘0C–?ýsystem,“through“its“special“data“type“called“a“"message“selector,"“provides“a“representationŽ¡‘0of–?ýoperations“that“is“flexible“enough“to“do“this,“but“the“C++“language“does“not.‘ ú(InŽ¡‘0C++,–?ýthe“compiler“requires“more“information“about“an“operation“than“the“event“structuresŽ¡‘0in–?ýSwarm“would“be“able“to“provide.)Ž¦ïhtml:ï html:Ÿ A‘0There's–?ýa“host“of“additional“reasons“why“Objective“C“has“also“been“a“good“match“forŽ¡‘0the–?ýrequirements“of“the“Swarm“system.‘ úLike“C++,“the“operations“on“objects“can“beŽ¡‘0compiled–?ýto“a“very“efficient“form“(though“Objective“C“does“require“a“little“more“overheadŽ¡‘0than–?ýC++“to“get“the“operation“started).‘ úThis“efficiency“can“be“very“important“forŽ¡‘0a–?ýsimulation,“since“simulations“can“run“for“very“long“periods“of“time“to“explore“allŽ¡‘0the–?ýbehavior“that“might“occur“within“their“simulated“worlds.‘ úOther“languages,“suchŽ¡‘0as–?ýLisp,“Smalltalk,“and“Java,“also“have“the“"dynamic“message“dispatch"“feature“thatŽ¡‘0would–?ýmake“general-purpose“event“structures“possible,“but“they“still“carry“significantŽ¡‘0added–?ýoverhead“compared“to“C.Ž¦ïhtml:ï html:Ÿ A‘0Objective–?ýC“is“also“a“very“simple“extension“to“the“C“language.‘ úBasic“knowledge“ofŽ¡‘0C–?ýis“already“widespread,“and“a“few“days“are“typically“all“that“is“needed“to“learnŽ¡‘0the–?ýfew“additions“of“Objective“C.“(Really“learning“the“concepts“of“objects,“however,Ž¡‘0can–?ýtake“much“longer,“no“matter“what“object“language“you“try“to“use.)Ž¦ïhtml:ï html:Ÿ A‘0Objective–?ýC“was“also“a“good“choice“for“Swarm“because“it“has“a“high“quality,“freelyŽ¡‘0distributable–?ýimplementation“in“the“GNU“C“compiler.‘ úOne“of“the“main“concerns“aboutŽ¡‘0Objective–?ýC“is“that“it“isn't“nearly“as“widely“known“or“used“as“other“languages“likeŽ¡‘0C++,–?ýbut“at“least“the“GNU“C“compiler“assures“it“will“be“available“on“machines“whereŽ¡‘0Swarm–?ýneeds“to“run.‘ úThe“OpenStep“system“of“the“NeXT“corporation,“and“the“parallelŽ¡‘0GNUStep–?ýproject,“also“help“assure“that“Objective“C“is“a“living“language.Ž¦ïhtml:ï html:Ÿ A‘0There–?ýare“even“more“powerful“aspects“of“Objective“C“that“Swarm“takes“advantage“of.Ž¡‘0Some–?ýof“these“are“described“in“the“ïhtml:ï html:Advanced“Usage“Guideïhtml:ï html:ŽŸI%‘0(adv.html)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹-óT “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿of–?ýthe“defobj“library.‘ úBut“many“others“are“at“the“heart“of“how“Swarm“uses“ObjectiveŽ¤‘/ºâC,–?ýand“so“are“dealt“with“in“the“rest“of“this“Usage“Guide.‘ úThe“entire“purpose“of“theŽ¡‘/ºâdefobj–?ýlibrary“is“to“define“a“standard“style“for“the“use“of“Objective“C“in“Swarm.Ž¡‘/ºâThis–?ýstyle“is“backed“up“by“a“library“of“foundation“classes“that“Swarm“provides“toŽ¡‘/ºâsupport–?ýthis“style.Žºâ©8äïhtml:ï html:Ÿ ÛO‘0Swarm–?ýprovides“its“own“foundation“classes“even“for“such“basic“operations“as“creatingŽ¡‘0an–?ýobject,“and“other“support“that“user“classes“ordinarily“receive“from“a“builtin“ObjectŽ¡‘0superclass.‘ úA–?ýgood“understanding“of“the“defobj“library“is“essential“for“ObjectiveŽ¡‘0C–?ýprogramming“in“Swarm.‘ úLike“any“programming“language,“Objective“C“requires“learningŽ¡‘0not–?ýonly“the“rules“of“the“language“itself,“but“also“a“standard“library“of“initialŽ¡‘0capabilities–?ýthat“you“build“from.‘ úObjective“C“doesn't“really“have“a“single“officialŽ¡‘0standard–?ýlibrary“(or“language“definition“either,“for“that“matter),“but“the“NextStepŽ¡‘0foundation–?ýlibraries“(and“the“NextStep“language“definition)“come“very“close“to“thisŽ¡‘0status.ŽŸïhtml:ï html:¤3‘0For–?ýa“variety“of“reasons“explained“here“and“in“the“ïhtml:ï html:Advanced“Usage“Guideïhtml:ï html:Ž¡‘0(adv.html)Ž¡‘0,–?ýSwarm“doesn't“use“a“standard“library“based“on“the“NextStep“foundation“interface.Ž¤‘0You–?ýcan“still“learn“the“Objective“C“language“from“other“available“sources,“but“youŽ¡‘0have–?ýto“be“careful“to“sort“out“the“language“level“from“the“standard“object“and“libraryŽ¡‘0support–?ýthey“also“discuss.Ž¦ïhtml:ï html:Ÿ ÛO‘0The–?ýïhtml:ï html:index“pageïhtml:ï html:Ž¤3‘0(../../index.html)Ž¡‘0of–?ýthe“Swarm“documentation“provides“a“variety“of“links“to“other“Objective“C“resources.Ž¤‘0In–?ýparticular,“it“provides“a“link“to“a“complete“on-line“reference“for“the“ObjectiveŽ¡‘0C–?ýlanguage“as“defined“by“NextStep“and“implemented“by“the“GNU“C“compiler.‘ úNone“ofŽ¡‘0the–?ýSwarm“documentation“attempts“to“duplicate“this“coverage“of“the“basic“language;Ž¡‘0Swarm–?ýassumes“that“you“learn“Objective“C“from“other“available“sources.‘ úThe“NextStepŽ¡‘0reference(ïhtml:ï html:ïhtml:ï html:¾Object-Oriented–?ýProgramming“and“the“Objective“C“Language‘¼rïhtml:ï html:Ž¤3‘0¿(http://www.next.com/Pubs/Documents/OPENSTEP/ObjectiveC/objctoc.htm)Ž¡‘0)–?ýis“the“single“best“available“source,“and“it“can“also“be“ordered“as“a“hardcopy“bookŽŸ‘0from–?ýthe“ïhtml:ï html:NeXT“publications“pageïhtml:ï html:Ž¡‘0(//www.next.com/Pubs/Documents/OPENSTEP)Ž¡‘0.‘ úDon't–?ýtry“to“program“in“Objective“C“without“it.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:ŸÐÀSwarm–Qëstyle“of“Objecti•ÓÅv“e–QëC“Pr°gogrammingŽŸrh¿No–?ýmatter“where“you've“learned“to“program“in“Objective“C,“don't“try“to“use“Objective“C“in“SwarmŽ¤without–?ýunderstanding“the“special“ways“in“which“Swarm“adapts“its“use“of“the“language“and“theŽ¡language–?ýruntime“system.‘ úYour“place“to“find“this“information“is“right“here“in“the“defobj“library.Ž¡Defobj–?ýnot“only“provides“the“most“basic“layer“of“foundation“class“libraries“for“Swarm,“butŽ¡also–?ýserves“as“the“place“where“all“the“rules“and“guidelines“for“the“use“of“Objective“C“in“SwarmŽ¡are–?ýgathered“together.ŽŸ—ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹.ˆ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿Some–?ýof“these“rules“and“guidelines“don't“even“require“any“specific“software“to“implementŽ¤‘/ºâthem,–?ýbut“are“just“conventions“and“recommended“style“that“anyone“programming“in“ObjectiveŽ¡‘/ºâC–?ýcan“follow“when“their“goals“are“similar“to“those“of“Swarm,“and“to“a“large“extentŽ¡‘/ºâoften–?ýdo.‘ úThese“kinds“of“conventions“are“the“focus“of“this“section;“following“sectionsŽ¡‘/ºâdiscuss–?ýaspects“of“Swarm“Objective“C“style“that“depend“on“specific“software“support.Žºâ©8äïhtml:ï html:Ÿ Ç‘0Lots–?ýmore“to“come...‘ úFor“now,“see“ïhtml:ï html:Library“Interface“Conventionsïhtml:ï html:Ž¡‘0(library.html)Ž¡‘0for–?ýsome“of“this“information,“and“Swarm“tutorials“for“much“of“the“rest.ŽŸcïhtml:ï html:Ÿœs‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹/… “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™AdvÊìanced“Usage“GuideŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:©‘0¿(This–?ýsection“of“documentation“is“not“yet“available.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¡ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹0 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Interface“Refer |enceŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ MÀDependenciesŽ¤¬¿The–?ýdefobj“library“is“defined“and“documented“using“the“ïhtml:ï html:library“interface“conventionsïhtml:ï html:Ž¡(library.html)ŽŸMãestablished–?ýby“the“defobj“library.‘ úIt“imports“the“Object“superclass“and“other“standard“typeŽ¤definitions–?ýof“the“GNU“Objective“C“runtime“system.Ž©8äïhtml:ï html:Ÿ ÿ‘0The–?ýcollections“library“must“always“be“linked“along“with“the“defobj“library.‘ úEvenŽ¡‘0though–?ýthe“interface“definitions“of“defobj“do“not“depend“directly“on“collections,Ž¡‘0the–?ýimplementations“of“these“libraries“both“require“the“presence“of“the“other.‘ úOnlyŽ¡‘0the–?ýcollections“library“should“be“initialized“directly;“initialization“of“the“collectionsŽ¡‘0library–?ýautomatically“initializes“the“defobj“library“as“well.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ MÀContentsŽŸ ¢Âïhtml:ï html:Ÿïhtml:ï html:Ÿ V‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿DefinedObjectïhtml:ï html:Ž¤Mã‘0(DefinedObject.html)Ž¦ïhtml:ï html:Ÿ ÿ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Createïhtml:ï html:Ž¡‘0(Create.html)ŽŸÕSïhtml:ï html:Ÿx‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Dropïhtml:ï html:Ž¡‘0(Drop.html)Ž¦ïhtml:ï html:Ÿ ÿ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Zoneïhtml:ï html:Ž¡‘0(Zone.html)ŽŸÕSïhtml:ï html:Ÿx‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Symbolïhtml:ï html:Ž¡‘0(Symbol.html)Ž¦ïhtml:ï html:Ÿ ÿ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Warningïhtml:ï html:Ž¡‘0(Error.html)ŽŸÕSïhtml:ï html:©x‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Errorïhtml:ï html:Ž¡‘0(Error.html)ŽŸ ÕSïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿library–?ýinterface“conventionsïhtml:ï html:Ž¡‘0(library.html)ŽŸ8äïhtml:ï html:Ÿ ÿ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿miscellaneous‘?ýoperationsïhtml:ï html:Ž¡‘0(misc.html)ŽŸÕSïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹1P “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâïcolor push BlackÁlï color popŽŽ‘9ºâïhtml:ï html:¿module–?ýdefinition“conventionsïhtml:ï html:Ž¤‘/ºâ(module.html)Žºâ©ÕSïhtml:ï html:Ÿ*‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿create–?ýcombination“messagesïhtml:ï html:Ž¡‘0(combo.html)Ž¦ïhtml:ï html:Ÿ*‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿global–?ýportability“assumptionsïhtml:ï html:Ž¡‘0(globalport.html)Ž©8äïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿global‘?ýdefinitionsïhtml:ï html:Ž¡‘0(globaldef.html)ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹2' “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ"–ÅDenedObject–™™{“standard“support“f£×or“all“objectsŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸÛßÀSynopsisŽŸ âcïhtml:ï html:Ÿ›G‘0Â//Ž¤u‘0//–ffDefinedObject“--“object“with“defined“type“and“implementationŽ¡‘0//Ž¡‘0@deftype‘ffDefinedObjectŽ¡‘0-‘ffgetZone;Ž¡‘0-–ff(BOOL)“respondsTo:“(SEL)aSel;Ž¡‘0-‘ffgetClass;Ž¡¡‘0-–ff(ref_t)“addRef:“(notify_t)notifyFunction“withArgument:“(void“*)arg;Ž¡‘0-–ff(void)“removeRef:“(ref_t)refVal;Ž¡¡‘0-–ff(int)“compare:“anObject;Ž¡¡‘0-–ffperform:“(SEL)aSel;Ž¡‘0-–ffperform:“(SEL)aSel“with:“anObject1;Ž¡‘0-–ffperform:“(SEL)aSel“with:“anObject1“with:“anObj2;Ž¡‘0-–ffperform:“(SEL)aSel“with:“anObject1“with:“anObj2“with:“anObj3;Ž¡¡‘0-–ff(void)“setDisplayName:“(const“char“*)displayName;Ž¡‘0-–ff(const“char“*)getDisplayName;Ž¡¡‘0-–ff(void)“describe:“outputCharStream;Ž¡‘0-–ff(void)“xprint;Ž¡‘0-–ff(void)“xprintid;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸÛßÀDescriptionŽŸ}ª¿DefinedObject–?ýis“the“top-level“supertype“for“all“objects“that“follow“the“object“programmingŽ¤conventions–?ýof“the“defobj“library.‘ úThe“messages“defined“by“this“type“are“the“only“messagesŽ¡which–?ýshould“be“assumed“to“be“automatically“available“on“objects“that“follow“these“conventions.Ž¡In–?ýparticular,“use“of“messages“defined“by“the“Object“superclass“of“the“GNU“Objective“C“runtimeŽ¡should–?ýnot“generally“be“assumed“because“future“implementations“of“some“objects“might“not“giveŽ¡continued–?ýaccess“to“them.ŽŸ ^5ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹3+Ø “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿The–?ýDefinedObject“type“defines“a“minimum“of“standard“messages,“and“leaves“to“otherŽ¤‘/ºâtypes–?ýthe“definition“of“message“that“might“or“might“not“apply“in“any“general“way“toŽ¡‘/ºâparticular‘?ýobjects.ŽºâŸ8äïhtml:ï html:©Ç‘0„¤ŽŽŸffïhtml:ï html:Ÿ¿&ÅInherited‘™™beha£×viorŽŸO¿The–?ýDefinedObject“type“inherits“no“behavior“from“any“other“type.‘ úIt“is“the“top“of“the“interfaceŽ¡type–?ýhierarchy“for“objects“that“follow“the“defobj“programming“conventions.‘ úAll“objects“thatŽ¡follow–?ýthese“conventions“should“inherit“from“DefinedObject,“either“directly“or“indirectly“throughŽ¡other‘?ýtypes.ŽŸ Ü»ïhtml:ï html:¦‘0„¤ŽŽŸffïhtml:ï html:Ÿ¿&ÅDened‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ>X‘0Â-‘ffgetZone;Ž¤wx‘0-–ff(BOOL)“respondsTo:“(SEL)aSel;Ž¡‘0-‘ffgetClass;Ž¡¿The–?ýgetZone“message“returns“the“zone“in“which“the“object“was“created.› úThe“respondsTo:˜messageŽ¤returns–?ýtrue“if“the“object“implements“the“message“identified“by“the“selector“argument.‘ úToŽ¡implement–?ýa“message“means“only“that“some“method“will“receive“control“if“the“message“is“sentŽ¡to–?ýthe“object.› ú(The“method“could“still“raise“an“error.)˜The“respondsTo:˜message“is“implementedŽ¡by–?ýdirect“lookup“in“a“method“dispatch“table,“so“is“just“as“fast“as“a“normal“message“send.‘ úItŽ¡provides–?ýa“quick“way“to“test“whether“the“type“of“an“object“includes“a“particular“message.‘ úgetClassŽ¡returns–?ýthe“class“that“implements“the“current“behavior“of“an“object.ŽŸ8äïhtml:ï html:¦‘0„¤ŽŽŸffïhtml:ï html:Ÿ¿&ÅDened‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ>X‘0Â-–ff(ref_t)“addRef:“(notify_t)notifyFunction“withArgument:“(void“*)arg;Ž¤wx‘0-–ff(void)“removeRef:“(ref_t)refVal;Ž¡¿These–?ýmessages“add“or“remove“an“external“reference“to“an“object“that“is“notified“whenever“theŽ©object–?ýis“changed“or“relocated.‘ ú(More“details“to“follow.)ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:Ÿ >”‘0Â-–ff(int)“compare:“anObject;Ž¡¡‘0-–ffperform:“(SEL)aSel;Ž¡‘0-–ffperform:“(SEL)aSel“with:“anObject1;Ž¡‘0-–ffperform:“(SEL)aSel“with:“anObject1“with:“anObj2;Ž¡‘0-–ffperform:“(SEL)aSel“with:“anObject1“with:“anObj2“with:“anObj3;Ž¡¿These–?ýmessages“are“have“implementations“in“the“Object“superclass,“excppt“for“the“three-argumentŽ¦form–?ýof“perform:.‘ úThey“have“local“implementations“in“defobj,“however,“just“to“make“subclassingŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹434 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿from–?ýObject“unnecessary.‘ úThey“are“currently“the“only“messages“defined“in“Object“that“are“recommendedŽ©ºâfor–?ýuse“in“Swarm.Žºâ¤ïhtml:ï html:¡ïhtml:ï html:¦‘0Â-–ff(void)“setDisplayName:“(const“char“*)displayName;Ž¦‘0-–ff(const“char“*)getDisplayName;Ž¦¿These–?ýmessages“assign“a“character“string“as“a“name“that“identifies“an“object“for“display“orŽ¦debug–?ýpurposes.‘ úA“global“function,“xsetname(),“is“also“available“to“set“the“name“by“callingŽ¦the–?ýfunction“from“the“debugger.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:¤ Ç‘0Â-–ff(void)“describe:“outputCharStream;Ž¦‘0-–ff(void)“xprint;Ž¦‘0-–ff(void)“xprintid;Ž¦¿The–?ýdescribe:‘ úmessage“prints“a“brief“description“of“the“object“for“debug“purposes“to“the“objectŽ¦passed–?ýas“its“argument.‘ úThe“object“passed“as“the“outputCharStream“argument“must“accept“a“catC:Ž¦message–?ýas“defined“in“String“and“OutputStream“in“the“collections“library.‘ úParticular“objectŽ¦types–?ýmay“generate“object“description“strings“with“additional“information“beyond“the“built-inŽ¦default,–?ýwhich“is“just“to“print“the“hex“value“of“the“object“id“pointer“along“with“the“nameŽ¦of–?ýits“class,“and“the“display“name“of“the“object,“if“any.‘ úxprint“prints“the“standard“describeŽ¦string–?ýto“standard“output;“it“is“also“called“by“the“xprint“function“that“may“be“called“fromŽ¦the–?ýdebugger.‘ úxprintid“prints“just“a“one-line“describe“string,“consisting“of“the“built-inŽ¦default.ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:¡‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹5> “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸŠWÅCrš½«eate–™™{“cr˜eate“a“customized“instance“of“a“typeŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸC ÀSynopsisŽŸ âcïhtml:ï html:Ÿ ‘0Â//Ž¤‡6‘0//–ffCreate“--“create“a“customized“instance“of“a“typeŽ¡‘0//Ž¡‘0@deftype–ffCreate“Ž¡‘0CREATINGŽ¡‘0+–ffcreate:“aZone;Ž¡‘0+–ffcreateBegin:“aZone;Ž¡‘0-‘ffcreateEnd;Ž¡¡‘0+–ffcustomizeBegin:“aZone;Ž¡‘0-‘ffcustomizeEnd;Ž¡‘0-–ffcustomizeCopy:“aZone;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸC ÀDescriptionŽŸåk¿The–?ýCreate“supertype“defines“standard“messages“that“provide“a“general-purpose“protocol“forŽ¤creating–?ýnew“objects.‘ úThese“messages“may“be“used“either“to“create“a“new“instance“of“a“typeŽ¡in–?ýone“message,“or“to“bracket“a“series“of“messages“that“customize“available“options“for“anŽ¡object–?ýto“be“created.‘ úThe“separation“of“create-time“specifications“from“later“behavior“ofŽ¡an–?ýobject“gives“substantial“flexibility“to“adapt“a“generic“type“to“particular“needs.ŽŸ—ïhtml:ï html:© NR‘0These–?ýcreate“messages“may“be“implemented“either“by“a“type“that“hides“its“implementingŽ¡‘0classes,–?ýor“directly“by“a“class“that“adopts“these“messages“as“a“uniform“interfaceŽ¡‘0for–?ýcreating“objects.‘ úIf“implemented“directly“by“a“class,“then“the“class“object“servesŽ¡‘0as–?ýthe“type“object“in“all“message“descriptions“that“follow.‘ úOtherwise,“a“type“objectŽ¡‘0might–?ýbe“implemented“in“a“variety“of“ways“that“guarantee“only“that“published“messagesŽ¡‘0on–?ýa“type“are“accepted.ŽŸ8äïhtml:ï html:¦‘0In–?ýaddition“to“the“create“messages“defined“by“Create,“an“object“type“may“support“anyŽ¡‘0other–?ýmessages“of“any“other“names“or“calling“conventions.‘ úThese“messages“define“onlyŽ¡‘0a–?ýstandard“method“for“creating“new“objects“that“other“types“are“free“to“inherit“andŽ¡‘0implement–?ýin“conformance“with“a“uniform“convention.‘ úFurther“conventions“are“establishedŽ¡‘0elsewhere–?ý(ïhtml:ï html:create“combination“messagesïhtml:ï html:ŽŸ‡6‘0(combo.html)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹6Eâ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿)–?ýfor“standard“ways“in“which“create“messages“that“combine“several“steps“can“be“combined.ŽŸ‘/ºâ„¤ŽŽºâ©ffïhtml:ï html:Ÿ_“ÅInherited‘™™beha£×viorŽ¤»¼¿The–?ýCreate“type“has“no“inherited“behavior“beyond“the“universal“messages“of“the“ïhtml:ï html:DefinedObjectïhtml:ï html:Ž¡(DefinedObject.html)Ž¤åtype.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:Ÿ_“ÅDened‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸÞÅ‘0Â+–ffcreate:“aZone;Ž¡¿The–?ýcreate:› úmessage“creates“a“new“instance“of“a“type“with“default“options.˜The“zone“argumentŽ¤specifies–?ýthe“source“of“storage“for“the“new“object.‘ úThe“receiving“object“of“this“message“isŽ¡a–?ýpreviously“defined“type“object.‘ úThe“message“is“declared“as“a“class“message“(with“a“+“declarationŽ¡tag)–?ýto“indicate“that“the“message“is“accepted“only“by“the“type“object“itself“rather“than“anŽ¡already–?ýcreated“instance“of“the“type“(which“a“-“declaration“tag“otherwise“defines).Ž¤8äïhtml:ï html:Ÿ ß‘0The–?ýcreate:‘ úmessage“returns“the“new“object“just“created.Ž¡ïhtml:ï html:¦ïhtml:ï html:Ÿ&¯ÅDened‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸÞÅ‘0Â+–ffcreate:“aZone;ŽŸå¿The–?ýcreate:› úmessage“creates“a“new“instance“of“a“type“with“default“options.˜The“zone“argumentŽ¤specifies–?ýthe“source“of“storage“for“the“new“object.‘ úThe“receiving“object“of“this“message“isŽ¡a–?ýpreviously“defined“type“object.‘ úThe“message“is“identified“as“a“class“message“(a“+“declarationŽ¡tag)–?ýto“indicate“that“the“message“is“accepted“only“by“the“type“object“itself“rather“than“anŽ¡already–?ýcreated“instance“of“the“type,“which“most“messages“of“a“type“(those“with“a“-“declarationŽ¡tag)–?ýotherwise“define.Ž©8äïhtml:ï html:Ÿ ß‘0The–?ýcreate:› úmessage“returns“the“new“object“just“created.˜This“object“is“an“instanceŽ¡‘0of–?ýsome“class“selected“to“implement“the“type.‘ úThe“class“which“a“type“selects“to“implementŽ¡‘0an–?ýobject“may“be“obtained“by“the“getClass“message,“but“is“not“otherwise“visible“toŽ¡‘0the–?ýcalling“program.‘ úA“caller“never“refers“to“any“class“name“when“creating“objectsŽ¡‘0using–?ýthese“messages,“only“to“type“names,“which“are“automatically“published“as“globalŽ¡‘0constants–?ýfrom“any“@deftype“declaration.Ž¦ïhtml:ï html:Ÿ ß‘0Â+–ffcreateBegin:“aZone;Ž¤å‘0-‘ffcreateEnd;Ž¡¿The–?ýcreateBegin:‘ úand“createEnd“messages“bracket“a“series“of“messages“that“specify“optionsŽ¤for–?ýan“object“being“created.‘ úThe“intermediate“messages“can“set“values“defined“as“parametersŽ¡of–?ýthe“type,“or“provide“other“forms“of“specification“using“available“messages.‘ úA“particularŽ¡object–?ýtype“defines“the“specific“messages“that“are“valid“for“sending“during“this“interim“creationŽ¡phase.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹7O\ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0¿createBegin:‘ úreturns–?ýan“interim“object“intended“only“for“receiving“create-time“messages.Ž¤‘0If–?ýa“type“was“defined“by“a“@deftype“declaration,“these“messages“are“those“appearingŽ¡‘0in–?ýeither“the“CREATING“or“SETTING“sections.‘ úOtherwise,“the“messages“valid“as“create-timeŽ¡‘0messages–?ýare“defined“by“the“type“without“any“specific“syntactic“marker.Ž©8äïhtml:ï html:Ÿ `¶‘0The–?ýcreateEnd“message“completes“the“process“of“specifying“available“options“for“anŽ¡‘0object–?ýbeing“created.‘ úTypically“it“validates“that“requested“options“are“valid“andŽ¡‘0consistent–?ýwith“one“another,“and“raises“an“error“if“they“are“not.‘ úThe“standard,“predefinedŽ¡‘0error‘?ýïhtml:ï html:InvalidCombinationïhtml:ï html:Ž¤™š‘0(Error.html#stderr)Ž¡‘0may–?ýbe“raised“by“createEnd“to“indicate“an“invalid“combination“of“requests,“or“other,Ž¤‘0more–?ýspecific“forms“of“error“handling“may“be“used.Ž¦ïhtml:ï html:Ÿ `¶‘0If–?ýall“requests“received“since“the“initial“createBegin:‘ úare“valid,“both“individuallyŽ¡‘0and–?ýin“combination“with“each“other,“then“createEnd“determines“a“finalized“form“ofŽ¡‘0object–?ýthat“satisfies“all“requests“received“and“then“returns“this“object.‘ úAny“additionalŽ¡‘0storage–?ýrequired“for“the“finalized“object“is“taken“from“the“same“zone“originally“passedŽ¡‘0to–?ýcreateBegin.‘ úThe“object“may“have“whatever“implementation“is“selected“to“best“satisfyŽ¡‘0a–?ýparticular“request.‘ úDifferent“requests“may“result“in“entirely“different“implementationsŽ¡‘0being–?ýreturned.‘ úThe“only“guarantee“is“that“a“returned“object“supports“the“messagesŽ¡‘0defined–?ýfor“further“use“of“the“finalized“object.‘ úIf“a“type“was“defined“by“a“@deftypeŽ¡‘0declaration,–?ýthese“messages“are“those“appearing“in“either“the“SETTING“or“USING“sections.Ž¦ïhtml:ï html:Ÿ `¶‘0On–?ýreturn“from“createEnd,“the“id“of“the“interim“object“returned“by“createBegin:‘ úisŽ¡‘0no–?ýlonger“guaranteed“to“be“valid“for“further“use,“and“should“no“longer“be“referenced.Ž¡‘0A–?ývariable“which“holds“this“such“an“id“can“be“reassigned“the“new“id“returned“by“createEnd,Ž¡‘0so–?ýthat“the“same“variable“holds“successive“versions“of“the“object“being“created.‘ úFollowingŽ¡‘0is–?ýa“fragment“that“illustrates“typical“coding“practice“using“createBegin:‘ úand“createEnd:Ž¦ïhtml:ï html:©ïhtml:ï html:Ÿ `¶‘0ÂnewArray–ff=“[Array“createBegin:“aZone];Ž¤™š‘:ÌÌ[newArray–ffsetInitialValue:“aList];Ž¡‘:ÌÌ[newArray–ffsetDefaultMember:“UnsetMember];Ž¡‘:ÌÌ[newArray–ffsetCount:“[aList“getCount]“*“2“);Ž¡‘:ÌÌnewArray–ff=“[newArray“createEnd];‘32//“!“note“reassignment“of“newArrayŽ¡¿By–?ýresetting“the“variable“to“the“returned“value“of“createEnd,“there“is“no“possibility“thatŽ¤the–?ýid“value“first“returned“by“createBegin:› úcan“ever“be“used“again.˜Sometimes,“the“id“valueŽ¡returned–?ýby“createEnd“might“be“the“same“value“first“returned“by“createBegin:,“if“createBegin:Ž¡was–?ýable“to“allocate“the“same“object“returned“later“by“createEnd.‘ úIn“other“cases,“however,Ž¡the–?ýobject“returned“by“createBegin:‘ úmight“be“strictly“a“temporary“object“that“is“thrown“awayŽ¡after–?ýcreateEnd“determines“a“final“object“to“be“created“and“returned.‘ úTo“protect“against“changesŽ¡in–?ýimplementation,“only“the“final“createEnd“return“value“should“ever“be“used“again“after“createEndŽ¡has‘?ýreturned.Ž¦ïhtml:ï html:¦ïhtml:ï html:¤™š‘0Â+–ffcustomizeBegin:“aZone;Ž¡‘0-‘ffcustomizeEnd;Ž¡‘0-–ffcustomizeCopy:“aZone;Ž¡¿Some–?ýtypes“accept“create-time“messages“not“only“when“creating“a“new“instance,“but“to“customizeŽ¤a–?ýnew“version“of“the“type“itself.‘ úObjects“created“from“a“customized“type“will“have“all“optionsŽ¡preset–?ýthat“create-time“messages“sent“to“the“customized“type“object“have“already“set.‘ úIf“manyŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹8[£ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿objects–?ýall“need“the“same“create-time“options,“it“is“often“simpler“(and“can“also“be“faster)Ž¤ºâto–?ýcreate“a“customized“version“of“a“type“first,“and“then“create“further“instances“from“thatŽ¡ºâtype.Žºâ©8äïhtml:ï html:Ÿ à¶‘0Customizing–?ýa“type“object“does“not“modify“the“original“type“object,“but“instead“createsŽ¡‘0a–?ýnew“type“object“that“has“the“customizations“built-in.› úA“create:˜message“on“theŽ¡‘0new–?ýtype“object“creates“a“new“instance“as“if“the“same“sequence“of“create-time“messagesŽ¡‘0had–?ýbeen“sent“to“the“original“type“object“using“createBegin:› úand“createEnd.˜A“typeŽ¡‘0is–?ýcustomized“by“bracketing“the“sequence“of“create-time“messages“not“with“the“createBegin:Ž¡‘0and–?ýcreateEnd“messages“used“to“create“a“new“instance,“but“with“customizeBegin:‘ úandŽ¡‘0customizeEnd–?ýmessages“instead.– úcustomizeBegin:“returns–?ýan“interim“value“for“receivingŽ¡‘0create-time–?ýmessages“much“like“createBegin:,“and“customizeEnd“returns“the“new,“customizedŽ¡‘0version–?ýof“the“original“type.‘ úFollowing“is“sample“code“sequence“that“illustratesŽ¡‘0the–?ýuse“of“these“messages:Ž¦ïhtml:ï html:Ÿ à¶‘0ÂnewArrayType–ff=“[Array“customizeBegin:“aZone];Ž¤š‘:ÌÌ[newArrayType–ffsetCount:“100];Ž¡‘:ÌÌnewArrayType–ff=“[newArrayType“customizeEnd];Ž¡‘:ÌÌarray1–ff=“[newArrayType“create:“aZone];Ž¡‘:ÌÌarray2–ff=“[newArrayType“create:“aZone];Ž¡‘:ÌÌ...–ff//“[array1“getCount]“and“[array2“getCount]“are“both“100Ž¡¿The–?ýcustomizeCopy:‘ úmessage“creates“a“new“copy“of“the“interim“object“returned“by“customizeBegin:Ž¤which–?ýmay“be“used“for“further“customizations“that“do“not“affect“the“customization“already“inŽ¡progress.‘ úIt–?ýmay“be“used“to“branch“off“a“path“of“a“customization“in“progress“to“create“anŽ¡alternate–?ýfinal“customization.‘ úFollowing“is“a“code“fragrment“which“illustrates“this“usage:Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ à¶‘0ÂnewArrayType1–ff=“[Array“customizeBegin:“aZone];Ž¤š‘:ÌÌ[newArrayType1–ffsetCount:“100];Ž¡‘:ÌÌnewArrayType2–ff=“[newArrayType2“customizeCopy:“aZone];Ž¡‘:ÌÌ[newArrayType2–ffsetDefaultMember:“UnsetMember];Ž¡¡‘:ÌÌnewArrayType1–ff=“[newArrayType1“customizeEnd];Ž¡‘:ÌÌnewArrayType2–ff=“[newArrayType2“customizeEnd];Ž¡‘:ÌÌarray1–ff=“[newArrayType1“create:“aZone];‘ ÌÌ//“no“DefaultMember“optionŽ¡‘:ÌÌarray2–ff=“[newArrayType“create:“aZone];‘32//“DefaultMember“option“setŽ¡¿customizeCopy–?ýmay“be“used“only“on“an“interim“object“returned“by“customizeBegin:‘ úand“not“yetŽ¤finalized–?ýby“customizeEnd.‘ úThe“new“version“of“the“interim“object“being“customized“may“be“allocatedŽ¡in–?ýthe“same“or“different“zone“as“the“original“version,“using“the“zone“argument“required“byŽ¡customizeCopy:Ž¦ïhtml:ï html:Ÿ à¶‘0The–?ýzone“passed“to“customizeBegin:‘ úis“the“same“zone“from“which“storage“for“the“new,Ž¡‘0finalized–?ýtype“object“will“be“taken.‘ úThis“zone“need“not“be“the“same“as“any“instanceŽ¡‘0later–?ýcreated“from“that“type,“since“a“new“zone“argument“is“still“passed“in“any“subsequentŽ¡‘0create–?ýmessage“on“that“type.Ž¦ïhtml:ï html:Ÿ à¶‘0Whether–?ýa“customized“version“of“a“type“can“be“created“depends“on“the“implementationŽ¡‘0of–?ýthe“type“itself.› úIf“a“type“does“not“support“customization,“a“customizeBegin:˜messageŽ¡‘0on–?ýthe“type“raises“an“error.‘ úAll“types“defined“by“an“@deftype“declaration“may“beŽ¡‘0relied–?ýon“to“support“at“least“one“cycle“of“customization“to“create“a“new“type“object.Ž¡‘0Whether–?ýan“already“customized“type“object“(returned“by“customizeEnd)“supports“a“furtherŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹9l “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿cycle–?ýof“customization“(by“another“sequence“of“customizeBegin:/customizeEnd)“dependsŽ¤‘/ºâon–?ýthe“implementation“of“the“original“starting“type.‘ úA“type“should“not“be“reliedŽ¡‘/ºâon–?ýto“support“more“than“one“cycle“of“customization“unless“it“is“specifically“documentedŽ¡‘/ºâto–?ýdo“so.ŽºâŸïhtml:ï html:¡‘0Any–?ýinterim“object“returned“by“either“createBegin:› úor“customizeBegin:˜supports“theŽ¡‘0getZone–?ýand“drop“messages“that“a“finalized“instance“may“also“support.‘ úThese“messagesŽ¡‘0are–?ýdefined“by“the“ïhtml:ï html:Dropïhtml:ï html:Ž¡‘0(Drop.html)Ž¡‘0type,–?ýwhich“is“normally“inherited“by“a“type“to“declare“these“messages“on“a“finalizedŽ¡‘0instance.‘ úThis–?ýtype“is“not“inherited“by“the“Create“type“because“the“messages“wouldŽ¡‘0then–?ýapply“to“the“finalized“instance,“not“to“the“interim“object.‘ úEven“though“notŽ¡‘0declared,–?ýthe“messages“are“available“on“the“interim“objects“nonetheless.‘ úThe“dropŽ¡‘0message–?ýon“an“interim“object“may“be“used“if“it“turns“out“that“a“finalized“versionŽ¡‘0is–?ýno“longer“required“after“creation“or“customization“has“already“begun.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹:{> “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ¬%ÅDr½«op–™™{“end“existence“of“an“objectŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸenÀSynopsisŽŸ âcïhtml:ï html:Ÿ $Ö‘0Â//Ž¤©‘0//–ffDrop“--“end“existence“of“an“objectŽ¡‘0//Ž¡‘0@deftype‘ffDropŽ¡‘0-–ff(void)“drop;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸenÀDescriptionŽŸ9¿The–?ýDrop“supertype“defines“the“drop“message,“which“is“a“standard“message“for“indicating“thatŽ¤an–?ýobject“no“longer“exists“and“will“never“again“be“referenced.‘ úAny“future“attempt“to“referenceŽ¡a–?ýdropped“object“is“an“error.‘ úThis“error“may“or“not“produce“predictable“effects“dependingŽ¡on–?ýthe“level“of“debug“checking“and“other“factors.ŽŸ—ïhtml:ï html:© p ‘0Immediate–?ýeffects“of“the“drop“message“depends“on“the“subtype“of“ïhtml:ï html:Zoneïhtml:ï html:Ž¤©‘0(Zone.html)Ž¡‘0used–?ýto“provide“storage“for“the“object.‘ úFor“some“zone“types,“the“drop“message“immediatelyŽ¤‘0deallocates–?ýstorage“for“the“object“and“makes“the“freed“storage“available“for“otherŽ¡‘0use.‘ úSubsequent–?ýuse“could“include“the“allocation“of“a“new“object“at“precisely“theŽ¡‘0same–?ýlocation,“resulting“in“a“new“object“id“identical“to“a“previously“dropped“one.Ž¡‘0Other–?ýzone“types“(..none“implemented“yet..)‘ úmight“delay“any“reclamation“of“freedŽ¡‘0storage–?ýuntil“a“more“comprehensive“check“can“be“made“that“other“references“no“longerŽ¡‘0exist–?ýto“the“dropped“object.‘ úWhen“running“in“debug“mode“(see“ïhtml:ï html:debug“supportïhtml:ï html:Ž¤©‘0(globaldef.html#debug)Ž¡‘0)–?ýthe“storage“for“a“dropped“object“is“filled“with“predictable“contents“so“that“anŽ¤‘0error–?ýis“raised“if“there“is“any“immediate“attempt“to“us“it“again.ŽŸ8äïhtml:ï html:¦‘0The–?ýDrop“type“may“be“inherited“by“any“type“that“provides“drop“support“for“its“instances.Ž¡‘0In–?ýaddition“to“freeing“the“storage“and“invalidating“the“object,“a“drop“message“mayŽ¡‘0release–?ýother“resources“acquired“or“held“within“the“object.‘ úNot“every“object“whichŽ¡‘0can–?ýbe“created“can“also“be“dropped,“and“some“objects“can“be“dropped“which“are“notŽ¡‘0directly–?ýcreatable.‘ úSome“objects“may“be“created“as“a“side“effect“of“other“operationsŽ¡‘0and–?ýstill“be“droppable,“and“some“objects“may“be“created“with“links“to“other“objectsŽ¡‘0and–?ýnot“droppable“on“their“own.‘ úA“type“independently“inherits“Create“or“Drop“types,Ž¡‘0or–?ýboth,“to“indicate“its“support“of“these“standard“interfaces“to“define“the“endpointsŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹;ê “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿of–?ýan“object“lifecycle.Žºâ©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹<A “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ&ÅZone–™™{“modular“unit“of“storage“allocationŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¾oÀSynopsisŽŸ âcïhtml:ï html:Ÿ}×‘0Â//Ž¤‘0//–ffZone“--“modular“unit“of“storage“allocationŽ¡‘0//Ž¡‘0@deftype–ffZone“Ž¡‘0CREATINGŽ¡‘0-–ff(void)“setReclaimPolicy:“reclaimPolicy;Ž¡‘0-–ff(void)“setStackedSubzones:“(BOOL)stackedSubzones;Ž¡‘0-–ff(void)“setPageSize:“(int)pageSize;Ž¡‘0USINGŽ¡‘0-‘ffgetReclaimPolicy;Ž¡‘0-–ff(BOOL)“getStackedSubzones;Ž¡‘0-–ff(int)“getPageSize;Ž¡¡‘0-–ffallocIVars:“aClass;Ž¡‘0-–ffcopyIVars:“anObject;Ž¡‘0-–ff(void)“freeIVars:“anObject;Ž¡¡‘0-–ffallocIVarsComponent:“aClass;Ž¡‘0-–ffcopyIVarsComponent:“anObject;Ž¡‘0-–ff(void)“freeIVarsComponent:“anObject;Ž¡¡‘0-‘ffgetComponentZone;Ž¡¡‘0-–ff(void“*)“alloc:“(size_t)size;Ž¡‘0-–ff(void)“free:“(void“*)aBlock;Ž¡¡‘0-–ff(void“*)“allocBlock:“(size_t)size;Ž¡‘0-–ff(void)“freeBlock:“(void“*)aBlock“blockSize:“(size_t)size;Ž¡¡‘0-‘PÿúgetPopulation;Ž¡‘0-‘ffgetSubzones;Ž¡‘0-–ff(void)“mergeWithOwner;Ž¡¡‘0-–ff(BOOL)“containsAlloc:“(void“*)alloc;Ž¡‘0-–ffgetSubzone:“(void“*)alloc;Ž¡¡‘0-–ff(void)“reclaimStorage;Ž¡‘0-–ff(void)“releaseStorage;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹=f “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤ ‘/ºâÂ-–ff(void)“xfprint;Ž¡‘/ºâ-–ff(void)“xfprintid;Ž¡‘/ºâ@endŽŸ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:ŸÎvÀDescriptionŽŸpA¿A–?ýzone“is“a“source“of“storage“for“objects“or“other“allocated“data.‘ úWhenever“a“new“object“isŽ¤created,–?ýa“zone“must“be“identified“from“which“the“storage“for“its“instance“variables,“or“otherŽ¡internal–?ýdata,“is“obtained.‘ úA“program“may“establish“multiple“zones“to“ensure“that“objectsŽ¡with–?ýsimilar“lifetime“or“storage“needs“are“allocated“together,“and“in“general“to“optimize“allocationŽ¡and–?ýreuse“of“storage.ŽŸ—ïhtml:ï html:© Ù(‘0Zones–?ýalso“maintain“a“collection“of“all“objects“allocated“within“the“zone.‘ úThis“collection,Ž¡‘0referred–?ýto“as“the“"population"“of“a“zone,“is“a“set“of“all“objects“which“have“beenŽ¡‘0created–?ýbut“not“yet“dropped“within“the“zone.‘ úCollections“maintained“automaticallyŽ¡‘0by–?ýzones“can“eliminate“a“need“for“other,“separately“maintained“collections“in“applicationsŽ¡‘0that–?ýneed“to“keep“track“of“entire“populations“of“objects.‘ úCollections“of“allocatedŽ¡‘0objects–?ýcan“provide“support“for“object“query,“external“object“storage,“and“automaticŽ¡‘0storage‘?ýreclamation.ŽŸ8äïhtml:ï html:¦‘0A–?ýzone“may“be“used“to“obtain“storage“not“only“for“objects,“but“also“for“raw“storageŽ¡‘0blocks–?ýlike“those“provided“by“the“C“malloc“function.‘ úAll“objects“and“storage“blocksŽ¡‘0allocated–?ýin“a“zone“remain“local“to“that“zone.‘ úThis“means“that“allocation“of“storageŽ¡‘0in–?ýother“zones“does“not“affect“the“efficiency“of“storage“allocation“within“a“particularŽ¡‘0zone.‘ úFor–?ýmost“zone“types,“individual“allocations“may“still“be“freed“within“a“zone,Ž¡‘0and–?ýtotal“storage“of“a“zone“may“grow“and“shrink“according“to“aggregate“needs.‘ úInŽ¡‘0addition–?ýto“freeing“individual“allocations,“an“entire“zone“may“also“dropped.‘ úDroppingŽ¡‘0a–?ýzone“automatically“frees“all“allocations“made“within“it,“including“final“drop“processingŽ¡‘0on–?ýany“allocated“objects“that“need“it.‘ úRelease“of“an“entire“zone“can“be“much“fasterŽ¡‘0than–?ýindividual“release“of“each“object“within“it.ŽŸ8äïhtml:ï html:¦‘0The–?ýZone“type“is“a“fully“implemented“type“that“provides“default“storage“managementŽ¡‘0support–?ýfor“objects“and“other“allocated“storage.‘ úIt“is“also“a“supertype“for“otherŽ¡‘0zones–?ýthat“implement“alternative“policies“for“use“in“specialized“situations.ŽŸ8äïhtml:ï html:¦‘0(..The–?ýcurrent“Zone“implementation“is“a“temporary“one“based“on“a“simple“pass-throughŽ¡‘0of–?ýall“allocation“requests“to“the“C“library“malloc“function.‘ úComplete“support“ofŽ¡‘0the–?ýzone“population“is“already“provided,“however,“as“is“support“for“internal“storageŽ¡‘0mapping–?ýthat“will“eventually“be“required“for“automatic“storage“reclamation“ConsiderableŽ¡‘0improvements–?ýin“storage“allocation“are“possible“when“the“current“implementation“isŽ¡‘0replaced–?ýby“more“efficient“allocation“contained“in“pages“local“to“each“zone.‘ ú..)ŽŸ8äïhtml:ï html:Ÿffïhtml:ï html:Ÿ ÖÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹>•| “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ@deftype–ffZone“Ž©aãºâ¿A–?ýzone“is“created“using“standard“create“messages“just“like“other“objects.‘ úThis“means“thatŽ¤ºâa–?ýzone“must“identify“another“zone“from“which“it“obtains“its“storage.‘ úStorage“is“typicallyŽ¡ºâobtained–?ýfrom“this“other“zone“in“large“units“called“pages,“which“are“then“managed“by“the“localŽ¡ºâzone–?ýto“support“internal“allocations.‘ úThe“getZone“message“of“the“ïhtml:ï html:Dropïhtml:ï html:Ž¦ºâ(Drop.html)Ž¦ºâtype–?ýreturns“the“zone“which“provides“these“base“pages.ŽºâŸ8äïhtml:ï html:Ÿ (ÿ‘0Since–?ýa“new“zone“always“requires“that“an“existing“zone“be“identified,“no“new“zonesŽ¡‘0could–?ýbe“created“unless“there“were“some“zones“that“already“existed.‘ úSeveral“suchŽ¡‘0zones–?ýare“predefined“as“part“of“the“defobj“library;“see“ïhtml:ï html:predefined“zonesïhtml:ï html:Ž¦‘0(globaldef.html#zones)Ž¦‘0for–?ýa“summary.ŽŸ8äïhtml:ï html:Ÿffïhtml:ï html:ŸpÅCr½«eate-time‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ(Ã‘0Â-–ff(void)“setReclaimPolicy:“reclaimPolicy;Ž¦‘0-–ff(void)“setStackedSubzones:“(BOOL)stackedSubzones;Ž¦‘0-–ff(void)“setPageSize:“(int)pageSize;Ž¦‘0USINGŽ¦‘0-‘ffgetReclaimPolicy;Ž¦‘0-–ff(BOOL)“getStackedSubzones;Ž¦‘0-–ff(int)“getPageSize;ŽŸ bÌïhtml:ï html:Ÿ e}‘0ÊReclaimPÂ“olicyŽ©•¿(..› úNot–?ýimplemented“yet.˜Will“define“the“various“types“of“zone“implementations,“all“the“wayŽ¡to–?ýzones“that“support“full“automatic“storage“reclamation.‘ ú..)ŽŸ lïhtml:ï html:¡ïhtml:ï html:Ÿe‘0ÊStackáIedSubzonesŽ¦¿(..› úNot–?ýimplemented“yet.˜Specifies“that“no“further“allocations“are“made“in“the“zone“afterŽ¡a–?ýsubzone“is“created,“until“that“subzone“itself“is“dropped.‘ úSupports“an“especially“efficientŽ¡of‘?ýimplementation.‘ ú..)ŽŸ lïhtml:ï html:¡ïhtml:ï html:Ÿe‘0ÊPáIageSizeŽ¦¿PageSize–?ýspecifies“the“size“of“pages“within“which“a“zone“manages“its“internal“allocation.‘ úItsŽ¡default–?ýis“typically“a“natural“page“size“(perhaps“4K)“for“the“local“machine“architecture.‘ úTheŽ¡default–?ýshould“be“overridden“only“when“tuning“storage“allocation“for“very“specific“situations.Ž¡Allocations–?ýwithin“a“zone“are“not“limited“to“the“page“size,“since“any“requests“that“exceedŽ¡the–?ýpage“size“are“simply“passed“up“to“the“owner“zone“within“which“the“zone“was“allocated.ŽŸ lïhtml:ï html:Ÿffïhtml:ï html:ŸpÅObject‘™™allocationŽŸ‘ýïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹?¢è “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ-–ffallocIVars:“aClass;Ž¤‹–‘/ºâ-–ffcopyIVars:“anObject;Ž¡‘/ºâ-–ff(void)“freeIVars:“anObject;Ž¡ºâ¿allocIVars:› úallocates–?ýthe“instance“variable“structure“for“a“new“object.˜The“initial“wordŽ¤ºâof–?ýthis“structure“is“set“to“class“id“passed“as“its“argument.‘ úThe“class“also“determines“theŽ¡ºâsize–?ýof“the“structure“allocated.‘ úAll“remaining“contents“of“this“structure“are“initializedŽ¡ºâto–?ýbinary“zeroes.Žºâ©8äïhtml:ï html:Ÿ R²‘0copyIVars:‘ úcreates–?ýcopies“an“existing“instance“variable“structure“into“a“new“allocationŽ¡‘0made–?ýwithin“the“local“zone.‘ úThe“existing“instance“variable“structure“may“be“in“anyŽ¡‘0zone,–?ýbut“must“contain“a“class“pointer“in“its“first“word“that“correctly“describesŽ¡‘0the–?ýsize“of“the“structure.ŽŸïhtml:ï html:Ÿ‹–‘0freeIVars:‘ úreleases–?ýstorage“that“was“previously“allocated“to“hold“the“instance“variableŽ¡‘0structure–?ýof“an“object.‘ úThe“first“word“of“the“object“must“be“a“class“pointer“thatŽ¡‘0correctly–?ýdescribes“the“size“of“the“structure.› úStorage“allocated“by“allocIVars:˜orŽ¡‘0copyIVars:› úmay–?ýbe“freed“only“by“freeIVars:,“and“freeIVars:˜may“be“used“only“to“freeŽ¡‘0storage–?ýallocated“by“one“of“these“messages.Ž¦ïhtml:ï html:Ÿ R²‘0The–?ýobject“allocation“functions“are“intended“for“use“only“within“the“implementationŽ¡‘0of–?ýan“object“class.‘ úUsers“of“an“object“type“should“create“a“new“object“only“usingŽ¡‘0create:‘ úmessages–?ýor“other“messages“provided“for“this“purpose.Ž¦ïhtml:ï html:Ÿffïhtml:ï html:Ÿš`ÅInterÈ½nal–™™component“objectsŽŸ‘ýïhtml:ï html:Ÿ p‘0Â-–ffallocIVarsComponent:“aClass;Ž¤‹–‘0-–ffcopyIVarsComponent:“anObject;Ž¡‘0-–ff(void)“freeIVarsComponent:“anObject;Ž¡¡‘0-‘ffgetComponentZone;Ž¡¿These–?ýmessages“allocate,“copy,“and“free“the“storage“that“holds“the“instance“variables“for“anŽ¤object,–?ýbut“they“allocate“the“object“as“an“internal“component“of“the“zone“that“is“not“includedŽ¡in–?ýthe“zone“population.‘ úThey“are“used“by“classes“that“allocate“additional“objects“as“partŽ¡of–?ýthe“implementation“of“another“object,“and“that“control“the“mapping“of“this“storage“separatelyŽ¡from–?ýthe“zone“level“objects.‘ úgetComponentZone“returns“a“specially“qualified“version“of“theŽ¡zone–?ýthat“automatically“allocates“all“its“objects“with“the“internal“component“qualification,Ž¡even–?ýif“allocated“with“allocIVars:› úor“copyIVars:.˜This“qualified“zone“may“be“passed“as“anŽ¡argument–?ýto“a“create:› úor“createBegin:˜message“so“that“it“will“create“the“new“object“as“anŽ¡internal–?ýcomponent“object.Ž¦ïhtml:ï html:Ÿffïhtml:ï html:Ÿš`ÅRaw–™™storage“block“allocationŽŸ‘ýïhtml:ï html:Ÿ p‘0Â-–ff(void“*)“alloc:“(size_t)size;Ž¤‹–‘0-–ff(void)“free:“(void“*)aBlock;Ž¡¡‘0-–ff(void“*)“allocBlock:“(size_t)size;Ž¡‘0-–ff(void“*)“copyBlock:“(void“*)aBlock“blockSize:“(size_t)size;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹@®= “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ-–ff(void)“freeBlock:“(void“*)aBlock“blockSize:“(size_t)size;ŽŸ %ºâ¿alloc:› úallocates–?ýa“new“storage“block“much“like“the“malloc“function“of“the“C“library.˜TheŽ¤ºâstorage–?ýis“aligned“according“to“the“most“restrictive“requirements“for“any“data“type“on“theŽ¡ºâlocal–?ýmachine“architecture.‘ úThe“storage“is“not“initialized“to“any“known“contents.Žºâ©8äïhtml:ï html:Ÿ ì‘0free:› úreleases–?ýa“block“of“storage“previously“allocated“using“alloc:.˜The“size“ofŽ¡‘0the–?ýblock“is“not“required“as“an“argument“because“alloc:‘ úhas“saved“this“size“as“necessaryŽ¡‘0as–?ýpart“of“the“initial“allocation.– úfree:“may–?ýbe“used“only“to“free“a“block“allocatedŽ¡‘0by–?ýalloc:,“and“a“block“allocated“by“alloc:‘ úmay“be“freed“only“by“free:.Ž¦ïhtml:ï html:Ÿ ì‘0allocBlock:‘ úallocates–?ýa“new“storage“block“similar“to“alloc:,“except“that“the“sizeŽ¡‘0of–?ýthe“block“allocated“must“be“passed“as“an“argument“when“freeing“the“block.‘ úcopyBlock:blockSize:Ž¡‘0allocates–?ýa“new“storage“with“the“same“requirements“on“free“as“allocBlock:,“but“alsoŽ¡‘0fills–?ýthe“new“storage“with“the“contents“of“a“block“passed“as“the“first“argument,“upŽ¡‘0to–?ýthe“size“of“the“newly“allocated“block.– úfreeBlock:blockSize:“must–?ýbe“used“to“freeŽ¡‘0any–?ýblock“previously“allocated“by“allocBlock:‘ úor“copyBlock:blockSize.Ž¦ïhtml:ï html:Ÿffïhtml:ï html:Ÿ3ÍÅSubzone‘™™structur½«eŽŸÜ÷ïhtml:ï html:Ÿëã‘0Â-‘PÿúgetPopulation;Ž¤ %‘0-‘ffgetSubzones;Ž¡‘0-–ff(void)“mergeWithOwner;Ž¡¡‘0-–ff(BOOL)“containsAlloc:“(void“*)alloc;Ž¡‘0-–ffgetSubzone:“(void“*)alloc;Ž¡¿getPopulation–?ýreturns“a“collection“all“objects“allocated“in“a“zone“using“either“allocIVars:Ž¤or–?ýcopyIVars:› úand“not“yet“freed“using“freeIVars:.˜getObjects“returns“nil“if“the“ObjectCollectionŽ¡option–?ýis“false.‘ úThe“collection“returned“has“the“type“ïhtml:ï html:OrderedSetïhtml:ï html:Ž¤ %(../collections/OrderedSet.html)Ž¡as–?ýdefined“in“the“ïhtml:ï html:collections“libraryïhtml:ï html:Ž¡(../collections.html)Ž¡,–?ýwith“the“ReadOnly“option“set“true“and“the“IndexSafety“option“set“to“SafeAlways.‘ úThe“membersŽ¤of–?ýthis“collection“may“change“as“objects“are“allocated“and“freed,“but“may“not“added“or“removedŽ¡directly–?ýwithin“the“collection.Ž¦ïhtml:ï html:Ÿ ì‘0getSubzones–?ýreturns“a“collection“of“other“zones“that“all“obtain“their“storage“fromŽ¡‘0the–?ýlocal“zone.‘ úmergeWithOwner“drops“the“local“zone,“but“reassigns“all“the“zone“allocationsŽ¡‘0to–?ýthe“zone“from“which“all“local“storage“was“obtained.‘ ú(..neither“message“currentlyŽ¡‘0implemented..)Ž¦ïhtml:ï html:Ÿ ì‘0containsAlloc:‘ útests–?ýif“a“particular“allocation“was“made“by“the“local“zone,“or“anyŽ¡‘0zone–?ýwhich“obtains“storage“from“that“zone.‘ úThe“pointer“argument“must“point“to“anŽ¡‘0allocation–?ýpreviously“made“by“any“zone.‘ úThe“message“returns“true“if“the“allocationŽ¡‘0was–?ýmade“by“either“the“local“zone“or“any“of“its“subzones.‘ úgetSubzone“is“similar,Ž¡‘0except–?ýthat“it“returns“the“particular“zone“in“which“the“pointer“was“allocated,“orŽ¡‘0nil–?ýif“the“pointer“was“not“allocated“in“the“local“zone“or“one“of“its“subzones.‘ ú(..neitherŽ¡‘0message–?ýcurrently“implemented..)Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Aºô “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹BÉS “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ„°ÅSymbol–™™{“object“dened“as“a“distinct“global“id“constantŽ©‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ=ùÀSynopsisŽŸ âcïhtml:ï html:Ÿýa‘0Â//Ž¤‘0//–ffSymbol“--“object“defined“as“a“distinct“global“id“constantŽ¡‘0//Ž¡‘0@deftype–ffSymbol“Ž¡‘0CREATINGŽ¡‘0+–ffcreate:“aZone“setName:“(const“char“*)name;Ž¡‘0-–ff(void)“setName:“(const“char“*)name;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ=ùÀDescriptionŽŸßÄ¿A–?ýSymbol“is“an“object“created“with“a“fixed“name.‘ úIt“has“no“behavior“except“to“get“the“nameŽ¤with–?ýwhich“it“was“created.‘ úA“Symbol“is“typically“used“to“define“unique“id“values“which“areŽ¡assigned–?ýto“global“constant“names.‘ úThese“names,“capitalized“according“to“the“recommended“conventionŽ¡for–?ýglobal“object“constants,“are“used“by“some“libraries“as“flags“or“enumerated“value“codesŽ¡in–?ýarguments“or“return“values“of“messages.ŽŸ—ïhtml:ï html:Ÿ H«‘0Ordinarily,–?ýa“symbol“is“created“with“its“character“string“name“matching“the“globalŽ¡‘0id–?ýconstant“to“which“it“is“assigned.‘ úThese“global“program“constants“can“then“provideŽ¡‘0a–?ýminimal“level“of“self“documentation“as“objects.‘ úSubtypes“of“Symbol“can“extend“theŽ¡‘0base–?ýof“a“named,“global“id“constant“to“establish“further“components“of“a“global,“constantŽ¡‘0definition.ŽŸïhtml:ï html:¦‘0„¤ŽŽŸffïhtml:ï html:ŸÉ=ÅInherited‘™™beha£×viorŽ©%f¿A–?ýsymbol“is“fully“creatable“using“standard“Create“messages.‘ úA“character“string“name“must“beŽ¡supplied–?ýfor“any“new“symbol;“there“is“no“default.‘ úSymbol“inherits“the“ïhtml:ï html:getNameïhtml:ï html:Ž¦(misc.html#GetName)ŽŸmessage,–?ýwhich“returns“the“symbol“name.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹CË3 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ÅCr½«eate–™™combination“messagesŽ©‘ýïhtml:ï html:Ÿ Ú‘0ÂCREATINGŽ¤‘0+–ffcreate:“aZone“setName:“(const“char“*)name;Ž¡¿create:setName:› úis–?ýa“combination“message“defined“as“a“caller“convenience.˜See“ïhtml:ï html:combinationŽ¡messagesïhtml:ï html:Ž¡(combo.html)Ž¡for–?ýa“summary“of“conventions“on“combination“messages.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŸG®ÅCr½«eate-time‘™™optionsŽ¦ïhtml:ï html:Ÿ Ú‘0ÂCREATINGŽ¡‘0-–ff(void)“setName:“(const“char“*)name;Ž¡¿The–?ýName“option“may“be“set“only“at“create“time.‘ úIts“value“is“a“null-terminated“character“stringŽ¡that–?ýremains“fixed“for“the“life“of“the“object.‘ úThe“inherited“getName“message“returns“thisŽ¡name–?ýfrom“a“created“instance.ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹DÓÁ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ¶ÅW‘ÿkarÈ½ning,–™™Errš½«or“{“r˜eport“of“some“condition“occurring“during“pr˜ogramŽ¤G®executionŽŸÜ÷ïhtml:ï html:ŸÖu‘0¿(..‘ úThis–?ýsection“of“documentation“is“only“a“start.)Ž©‘0„¤ŽŽ¡ïhtml:ï html:ŸËÿÀSynopsisŽŸ âcïhtml:ï html:Ÿ‹g‘0Â//Ž¤•‘0//–ffEventType“--“report“of“some“condition“occurring“during“program“executionŽ¡‘0//Ž¡‘0@deftype–ffEventType“Ž¡‘0-–ff(void)“raiseEvent;Ž¡‘0-–ff(void)“raiseEvent:“(void“*)eventData,“...;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffWarning“--“a“condition“of“possible“concern“to“a“program“developerŽ¡‘0//Ž¡‘0@deftype–ffWarning“Ž¡‘0-–ff(void)“setMessageString:“(const“char“*)messageString;Ž¡‘0-–ff(const“char“*)getMessageString;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffError“--“a“condition“which“prevents“further“executionŽ¡‘0//Ž¡‘0@deftype–ffError“Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸËÿÀDescriptionŽŸmÊ¿Warning–?ýand“Event“are“object“types“(both“subtypes“of“EventType)“that“may“be“used“to“reportŽ¤conditions–?ýdetected“during“program“execution.‘ úA“warning“is“a“condition“of“possible“interestŽ¡to–?ýa“developer“or“user,“but“one“that“does“not“prevent“further“execution.‘ úAn“error“is“a“conditionŽ¡which–?ýprevents“further“execution“of“the“program.ŽŸ—ïhtml:ï html:Ÿ Ö±‘0Warning–?ýand“Event“also“inherit“from“Symbol,“so“that“each“type“of“warning“or“errorŽ¡‘0may–?ýbe“given“a“unique“global“name.‘ úAny“library“may“publish“its“own“warning“and“eventŽ¡‘0names–?ýas“part“of“its“documented“library“interface“(see“ïhtml:ï html:module“definition“conventionsïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹EÙ< “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿(module.html)ŽŸ|î‘/ºâfor–?ýstandard“methods“of“declaring“interface“symbols“in“a“library“header“file.)Žºâ¤8äïhtml:ï html:© D ‘0These–?ýpredefined“warning“and“event“types“are“typically“used“not“directly“by“the“messagesŽŸ‘0defined–?ýabove,“but“by“the“following“macro“defined“in“defobj.h:Ž¡ïhtml:ï html:Ÿïhtml:ï html:¦‘0Â#define–ffraiseEvent(“eventType,“formatString,“args...“)Ž©|î¿This–?ýmacro“raises“an“event“of“the“type“identified“by“the“first“argument.‘ úDefault“handlingŽ¤of–?ýthe“event“is“to“print“a“formatted“message“including“standard“header“and“trailer“lines,“andŽ¡then–?ýeither“to“continue“(in“the“case“of“a“Warning)“or“to“terminate“the“program“in“the“caseŽ¡of–?ýError).‘ úThe“standard“header“lines“include“the“file,“function,“and“line“number“where“theŽ¡macro–?ýthat“raised“the“event“was“executed.ŽŸïhtml:ï html:¦‘0If–?ýthe“formatString“argument“is“nil,“a“default“message“string“already“establishedŽ¡‘0as–?ýpart“of“the“warning“or“event“type“is“used“to“report“the“error.‘ úOtherwise,“theŽ¡‘0formatString–?ýargument“must“be“a“null-terminated“C“character“string“that“overridesŽ¡‘0the–?ýdefault“string.Ž©8äïhtml:ï html:Ÿ D ‘0Either–?ýthe“default“or“replacement“message“string“may“contain“printf-style“formattedŽ¡‘0field–?ýdefinitions.‘ úFor“each“formatted“field“definition,“an“argument“value“must“beŽ¡‘0supplied–?ýin“the“args...› úsection“of“the“macro.˜(The“support“of“the“GNU“C“compilerŽ¡‘0for–?ýmacros“with“variable“argument“lists“is“used“by“the“macro.)Ž¦ïhtml:ï html:© D ‘0(..‘ úMethods–?ýfor“defining“new“event“types“as“part“of“a“library“implementation“areŽ¡‘0not–?ýcurrently“documented.‘ úInstead,“just“use“the“raiseEvent“macro“on“one“of“the“predefinedŽ¡‘0Warning–?ýor“Event“Types“if“you“want“to“raise“an“event“using“this“standard“mechanism.Ž¡‘0Eventually,–?ýthis“standard“mechanism“will“be“used“to“handle“warnings“and“errors“underŽ¡‘0various–?ýforms“of“logging“exception“handling“support.)ŽŸ€’ïhtml:ï html:ŸtÀStandard–QëErr°gor“and“W‘þàar½°ning“T‘þ¸¦ypesŽŸÛ#¿The–?ýfollowing“standard“error“and“warning“types“are“defined“by“the“defobj“library.‘ úThesy“mayŽ¡also–?ýbe“used“by“other“libraries“for“errors“or“warnings“that“fit“within“these“standard“predefinedŽ¡categories:ŽŸ—ïhtml:ï html:Ÿïhtml:ï html:¦‘0Â//Ž¤|î‘0//–ffstandard“errorsŽ¡‘0//Ž¡‘0extern–ffid“Ž¡‘:ÌÌSourceMessage,‘5ÿü//–ffmessage“in“the“source“defines“errorŽ¡‘:ÌÌNotImplemented,‘0™–//–ffrequested“behavior“not“implemented“by“objectŽ¡‘:ÌÌSubclassMustImplement,‘ ÌÌ//–ffrequested“behavior“must“be“imple-ŽŸ‘0mented–ffby“subclassŽ¡‘:ÌÌInvalidCombination,‘ÿþ//–ffinvalid“combination“of“set“messages“for“createŽ¡‘:ÌÌInvalidOperation,‘%ÌÊ//–ffinvalid“operation“for“current“state“of“receiverŽ¡‘:ÌÌInvalidArgument,‘+30//–ffargument“value“not“validŽ¡‘:ÌÌCreateSubclassing,‘ fd//–ffimproper“use“of“Create“subclassing“frameworkŽ¡‘:ÌÌCreateUsage,‘@ÌÈ//–ffincorrect“sequence“of“Create“protocol“messagesŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹FáI “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘:‡®ÂOutOfMemory,‘@ÌÈ//–ffno“more“memory“available“for“allocationŽ¤‘:‡®InvalidAllocSize,‘%ÌÊ//–ffno“more“memory“available“for“allocationŽ¡‘:‡®InternalError,‘5ÿü//–ffunexpected“condition“encountered“in“programŽ¡‘:‡®BlockedObjectAlloc,‘ÿþ//–ffmethod“from“Object“with“invalid“allocationŽ¡‘:‡®BlockedObjectUsage;‘ÿþ//–ffmethod“inherited“from“Object“superclassŽ¡¡‘/ºâ//Ž¡‘/ºâ//–ffstandard“warningsŽ¡‘/ºâ//Ž¡‘/ºâextern–ffid“Ž¡‘:‡®WarningMessage,‘0™–//–ffmessage“in“the“source“defines“warningŽ¡‘:‡®LibraryUsage,‘;fb//–ffinvalid“usage“of“library“interfaceŽ¡‘:‡®DefaultAssumed,‘0™–//–ffnon-silent“use“of“defaultŽ¡‘:‡®ObsoleteMessage,‘+30//–ffusing“feature“which“could“be“removed“in“futureŽ¡‘:‡®ObsoleteFeature,‘+30//–ffusing“feature“which“could“be“removed“in“futureŽ¡‘:‡®ResourceAvailability;‘32//–ffresource“from“runtime“environment“not“availableŽŸ‘/ºâ„¤ŽŽºâŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1997-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Gîˆ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Miscellaneous‘/OperationsŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:ŸPÀObject‘QëT‘þ¸¦ypesŽŸ¥¿The–?ýfollowing“object“types“are“documented“below:ŽŸ—ïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:¤ ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Copyïhtml:ï html:ŽŸ8äïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿GetNameïhtml:ï html:Ž¤¬ïhtml:ï html:©*:‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿GetOwnerïhtml:ï html:Ž¡ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SetInitialValueïhtml:ï html:ŽŸ‘0„¤ŽŽ©G®ïhtml:ï html:ŸPÀSummary–Qëof“Miscellaneous“OperationsŽŸ¥¿An–?ýassortment“of“object“types“in“the“defobj“library“serve“just“to“establish“a“single“declarationŽ¤of–?ýmessages“that“many“other“object“types“adopt“as“part“of“their“declared“interface.‘ úThe“centralizedŽ¡definition–?ýof“the“messages“in“these“types“avoids“their“repetition“throughout“many“other“types.Ž¡It–?ýalso“provides“a“single“place“where“basic“rules“for“these“messages“can“be“summarized“forŽ¡all–?ýother“implementations“to“follow.‘ úThis“reference“documentation“provides“these“summariesŽ¡along–?ýwith“intended“purpose“of“each“message.ŽŸ—ïhtml:ï html:Ÿ ‘0None–?ýof“these“types“inherits“from“any“other“types;“their“whole“purpose“is“just“toŽ¡‘0package–?ýthe“definition“of“one“or“more“messages.‘ úThe“type“name“is“typically“the“sameŽ¡‘0as–?ýa“message“declared“by“the“type,“only“with“the“uppercase“convention“of“a“type“name.Ž¡‘0These–?ýtypes“may“be“freely“mixed“into“the“inheritance“lists“of“other“types“to“buildŽ¡‘0whatever–?ýcombinations“of“messages“those“other“types“need“to“define.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:ŸPÀCopy–QëInterface“DescriptionŽŸê”ïhtml:ï html:Ÿ fÅSynopsisŽŸ‘ýïhtml:ï html:Ÿ XÀ‘0Â//Ž¤Fæ‘0//–ffCopy“--“copy“all“state“defined“as“part“of“objectŽ¡‘0//Ž¡‘0@deftype‘ffCopyŽ¡‘0-–ffcopy:“aZone;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹HóÛ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ@endŽºâ©ƒ/ïhtml:ï html:Ÿ^OÅDescriptionŽŸ×A¿The–?ýcopy“message“creates“a“new“object“that“has“the“same“contents“and“resulting“behavior“asŽ¤a–?ýstarting“object,“except“that“an“independent“copy“of“the“contents“of“the“starting“object“isŽ¡created–?ýso“that“further“changes“to“one“object“do“not“affect“the“other.‘ úThe“zone“argument“specifiesŽ¡the–?ýsource“of“storage“for“the“new“object.‘ úThe“message“returns“the“id“of“the“new“object“created.ŽŸ Ü»ïhtml:ï html:Ÿ ú†‘0An–?ýobject“type“that“supplies“the“copy“operation“defines“what“it“includes“as“the“contentsŽ¡‘0of–?ýan“object“copied.‘ úThere“is“no“global“rule“for“what“is“considered“"inside"“a“copiedŽ¡‘0object–?ývs.› úmerely“referenced“by“it.˜(There“is“no“fixed“notion“of“"shallow"“vs.˜"deep"Ž¡‘0copy–?ýfound“in“some“object“libraries.)‘ úAfter“copying,“the“new“object“may“still“containŽ¡‘0some–?ýreferences“to“other“elements“also“referenced“by“the“starting“object,“but“in“generalŽ¡‘0the–?ýnew“object“minimizes“any“dependencies“shared“with“the“starting“object.‘ úAny“objectŽ¡‘0type–?ýsupplying“the“copy“message“should“also“supply“documentation“on“its“rules“forŽ¡‘0copied‘?ýobjects.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:ŸïÔÀGetName–QëInterface“DescriptionŽŸê”ïhtml:ï html:Ÿ öêÅSynopsisŽŸ‘ýïhtml:ï html:Ÿ ED‘0Â//Ž¤3j‘0//–ffGetName“--“get“name“which“identifies“object“in“its“context“of“useŽ¡‘0//Ž¡‘0@deftype‘ffGetNameŽ¡‘0-–ff(const“char“*)“getName;Ž¡‘0@endŽ¦ïhtml:ï html:Ÿ^OÅDescriptionŽŸ×A¿The–?ýgetName“message“returns“a“null-terminated“character“string“that“identifies“an“object“inŽ¤some–?ýcontext“of“use.‘ úThis“message“is“commonly“used“for“objects“that“are“created“once“in“someŽ¡fixed–?ýcontext“where“they“are“also“assigned“a“unique“name.‘ úConstant“objects“defined“as“partŽ¡of–?ýa“program“or“library“are“examples.‘ úThis“message“is“intended“only“for“returning“a“name“associatedŽ¡with–?ýan“object“throughout“its“lifetime.‘ úIt“does“not“return“any“data“that“ever“changes.ŽŸ Ü»ïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:ŸïÔÀGetOwner–QëInterface“DescriptionŽŸê”ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Iýõ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅSynopsisŽºâ©‘ýïhtml:ï html:Ÿ T‘0Â//Ž¤ z‘0//–ffGetOwner“-“get“object“on“which“existence“of“object“dependsŽ¡‘0//Ž¡‘0@deftype‘ffGetOwnerŽ¡‘0-‘ffgetOwner;Ž¡‘0@endŽŸƒ/ïhtml:ï html:Ÿ5_ÅDescriptionŽŸ®Q¿The–?ýgetOwner“message“returns“another“object“which“is“considered“as“the“owner“of“an“initialŽ¤object.‘ úWhat–?ýis“considered“as“an“owner“depends“on“its“specific“object“type,“but“might“be“aŽ¡larger–?ýobject“of“which“the“local“object“is“a“part,“or“an“object“that“has“exclusive“controlŽ¡over–?ýthe“local“object.‘ úThe“principal“constraint“established“by“an“ownership“structure“is“thatŽ¡a–?ýgiven“object“can“have“only“a“single“other“object“as“its“unambiguous“owner.ŽŸ Ü»ïhtml:ï html:Ÿ Ñ–‘0Ownership–?ýhierarchies“arrange“themselves“in“a“strict,“single-rooted“tree.‘ úThe“top-levelŽ¡‘0node–?ýof“an“ownership“hierarchy“typically“returns“nil“as“its“owner.‘ úIf“an“object“isŽ¡‘0regarded–?ýmerely“as“one“part“of“another“object“defined“as“its“owner,“then“copying“orŽ¡‘0dropping–?ýthe“owner“object“should“copy“or“drop“the“member“object“as“well.‘ úOwner“andŽ¡‘0member–?ýare“neutral“terms“for“a“generic“relationship“sometimes“called“parent“vs.‘ úchild,Ž¡‘0but–?ýit“is“up“to“a“particular“object“type“to“define“specifically“what“it“means“by“aŽ¡‘0getOwner‘?ýrelationship.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:ŸÆäÀSetInitialV‘þialue–QëInterface“DescriptionŽŸê”ïhtml:ï html:Ÿ ÍúÅSynopsisŽ¦ïhtml:ï html:Ÿ T‘0Â//Ž¤ z‘0//–ffSetInitialValue“-“create“using“initial“value“from“an“existing“objectŽ¡‘0//Ž¡‘0@deftype‘ffSetInitialValueŽ¡‘0CREATINGŽ¡‘0+–ffcreate:“aZone“setInitialValue:“initialValue;Ž¡‘0+–ffcreate:“aZone“setReadOnlyValue:“readOnlyValue;Ž¡¡‘0-–ff(void)“setInitialValue:“initialValue;Ž¡‘0-–ff(void)“setReadOnlyValue:“readOnlyValue;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setReadOnly:“(BOOL)readOnly;Ž¡‘0USINGŽ¡‘0-–ff(BOOL)“getReadOnly;Ž¡‘0@endŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹JÝ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ÅDescriptionŽŸ£×¿The–?ýSetInitialValue“type“defines“a“variety“of“messages“relating“to“an“initial“or“unmodifiableŽ¤value–?ýestablished“as“part“of“an“object.‘ úThis“message“is“typically“provided“when“creation“ofŽ¡a–?ýnew“object“might“be“more“easily“accomplished“by“copying“the“value“of“an“existing“object“ratherŽ¡than–?ýestablishing“a“new“value“from“scratch.‘ úAs“with“the“copy“message,“precisely“what“is“consideredŽ¡the–?ývalue“of“an“existing“object“to“copy“is“defined“only“by“the“particular“object“type“thatŽ¡supplies–?ýthese“messages.ŽŸ Ü»ïhtml:ï html:© Ç‘0If–?ýan“object“has“a“value“which“can“be“established“at“create“time,“it“is“often“usefulŽ¡‘0(and–?ýcan“also“enable“significant“optimization)“to“declare“that“no“further“modificationŽ¡‘0will–?ýoccur“to“this“value“during“further“use“of“the“object.‘ úA“restriction“againstŽ¡‘0modifying–?ýa“value“is“referred“to“as“a“"read-only"“restriction.‘ úThis“type“suppliesŽ¡‘0messages–?ýto“declare“a“read-only“restriction“along“with“any“initial“value.‘ úFor“someŽ¡‘0object–?ýtypes,“a“read-only“restriction“can“also“be“added“or“removed“after“an“objectŽ¡‘0has–?ýalready“been“created.ŽŸ8äïhtml:ï html:¦‘0The–?ýsetInitialValue:‘ úmessage“requires“another“object“as“its“argument,“from“whichŽ¡‘0the–?ývalue“of“a“newly“created“object“is“to“be“taken.‘ úUnlike“a“copy“message,“the“objectŽ¡‘0used–?ýas“the“source“of“the“new“value“need“not“have“the“identical“type“as“the“new“objectŽ¡‘0to–?ýbe“created.‘ úA“particular“object“type“defines“the“types“of“initial“value“objectsŽ¡‘0which–?ýit“can“accept,“along“with“any“special“conversion“or“interpretation“it“mightŽ¡‘0apply–?ýto“such“a“value.ŽŸ8äïhtml:ï html:¦‘0The–?ýReadOnly“flag“specifies“that“the“value“of“an“object“may“not“be“modified“furtherŽ¡‘0by–?ýother“messages“on“an“object.‘ úIf“such“messages“are“attempted“then“an“error“is“raised.Ž¡‘0If–?ýthe“ReadOnly“flag“is“set“at“create“time,“the“object“is“first“created“in“read-onlyŽ¡‘0mode.‘ úTypically–?ýan“initial“value“is“always“provided“for“an“initial“read-only“object,Ž¡‘0since–?ýotherwise“the“created“object“would“have“only“an“empty“or“initial“default“value.Ž¡‘0The–?ýsetReadOnlyValue:‘ úmessage“is“equivalent“to“a“combination“of“a“setInitialValue:Ž¡‘0message–?ýwith“an“added“ReadOnly“restriction.ŽŸ8äïhtml:ï html:¦‘0If–?ýa“read-only“restriction“is“established“at“create“time,“then“for“some“object“typesŽ¡‘0this–?ýrestriction“may“be“required“to“remain“for“the“entire“lifetime“of“an“object.‘ úForŽ¡‘0other–?ýobject“types,“the“read-only“restriction“may“be“added“or“removed“any“time“afterŽ¡‘0initial–?ýobject“creation.‘ úIf“a“particular“type“does“not“support“a“change“to“read-onlyŽ¡‘0status,–?ýa“request“to“do“so“raises“an“error.ŽŸ8äïhtml:ï html:¦‘0Standard–?ýforms“of“ïhtml:ï html:create“combination“messagesïhtml:ï html:Ž¡‘0(combo.html)Ž¡‘0are–?ýprovided“to“create“an“object“in“one“message“expression“from“the“value“of“anotherŽ¡‘0object,–?ýwith“or“without“a“read-only“restriction.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹KÖ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Module–/Denition“Con‘ÿ+¶vÊìentionsŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:ŸòÀOv•ÓÅer“viewŽ¤“Í¿Some–?ýof“the“basic“Swarm“libraries“are“implemented“using“object“definition“conventions“establishedŽ©by–?ýthe“ïhtml:ï html:defobj“libraryïhtml:ï html:Ž¡(../defobj.html)ŽŸ5˜.‘ úThese–?ýconventions“include“some“minor“special“syntax“to“declare“the“public“interfaces“toŽ¦Objective–?ýC“objects.‘ úThis“document“explains“how“to“read“and“interpret“the“header“files“andŽ¦interface–?ýdefinitions“published“by“such“libraries.‘ úIt“also“explains“the“typical“structureŽ¦of–?ýdocumentation“provided“for“libraries“that“follow“these“conventions.Ž©8äïhtml:ï html:¤ ü´‘0These–?ýconventions“are“documented“under“the“following“subsections:ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿library–?ýheader“fileïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿object–?ýtype“definitionsïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿GridTurtle‘?ýexampleïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿global–?ýobject“symbolsïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿interface–?ýdesign“conventionsïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿documentation‘?ýstructureïhtml:ï html:ŽŸ‘0„¤ŽŽŸffïhtml:ï html:Ÿ}FÅLibrary–™™Header“FileŽŸÙo¿For–?ýa“library“that“adopts“these“conventions,“a“library“is“not“merely“a“collection“of“sourceŽ¤files–?ýthat“are“compiled“into“a“library“archive“under“control“of“a“make“file.‘ úInstead,“ObjectiveŽ¡C–?ýsource“files“in“the“library“are“processed“in“a“special“way“to“publish“their“definitions“notŽ¡only–?ýas“header“files,“but“as“generated“objects“available“at“runtime“to“make“full“use“of“theŽ¡library.‘ úA–?ýlibrary“processed“in“this“way“is“referred“to“as“as“a“"module."ŽŸ Ü»ïhtml:ï html:Ÿ ü´‘0The‘?ýïhtml:ï html:defobjïhtml:ï html:Ž¤5˜‘0(../defobj.html)Ž¡‘0library–?ýdocuments“the“full“details“of“special“processing“performed“on“a“module.‘ úForŽ¤‘0simply–?ýusing“a“library“defined“as“a“module,“the“key“fact“to“keep“in“mind“is“that“theŽ¡‘0entire–?ýpublic“interface“to“a“module“is“declared“in“the“one“header“file“having“theŽ¡‘0same–?ýname“as“the“module“itself,“plus“a“trailing“.h“suffix.‘ úAdditionally,“the“headerŽ¡‘0file–?ýof“a“library“module“normally“documents“only“the“public“interface“to“a“module,Ž¡‘0in–?ýa“way“that“is“completely“separated“from“the“implementation“of“the“objects“it“specifies.Ž¦ïhtml:ï html:Ÿ ü´‘0The–?ýseparation“of“implementation“means“that“a“library“module“publishes“its“interfaceŽ¡‘0entirely–?ýwithout“reference“to“any“Objective“C“classes“which“implement“its“objects.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Lm “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿Even–?ýthough“classes“are“often“thought“of“as“separating“the“interface“of“an“objectŽ¤‘/ºâfrom–?ýits“implementation,“this“separation“is“far“from“complete.‘ úNot“only“do“classesŽ¡‘/ºâtypically–?ýcontain“many“internal“methods“not“intended“for“external“use,“but“they“alsoŽ¡‘/ºâdefine–?ýa“particular“storage“format“for“an“object“defined“as“instance“variables.Žºâ©8äïhtml:ï html:Ÿ (d‘0A–?ýlibrary“module“instead“publishes“its“interface“as“a“set“of“public“object“types.Ž¡‘0These–?ýobject“types“may“also“be“supplemented“by“global“object“constants“called“symbols.Ž¡‘0Both–?ýthese“kinds“of“definitions“normally“appear“only“in“the“header“file“of“a“library.Ž¡‘0The–?ýremaining“source“files“in“a“library“normally“contain“the“classes“which“implementŽ¡‘0the–?ýobject“types.Ž¦ïhtml:ï html:Ÿ (d‘0In–?ýa“library“module,“the“files“which“implement“classes“(including“class“header“files),Ž¡‘0need–?ýnot“ever“be“referenced“simply“to“make“use“of“the“implemented“capabilities“ofŽ¡‘0the–?ýlibrary“object“types.‘ úDocumentation“for“the“library“is“normally“expressed“entirelyŽ¡‘0in–?ýterms“of“the“types“and“symbols“published“in“the“library“header“file.‘ úIf“a“featureŽ¡‘0does–?ýnot“appear“in“the“library“header“file,“it“should“not“be“considered“part“of“aŽ¡‘0supported–?ýpublic“interface.Ž¦ïhtml:ï html:Ÿ (d‘0Individual–?ýclass“header“files“are“required“to“subclass“from“existing“implementations,Ž¡‘0but–?ýinterfaces“for“subclassing“are“an“entirely“separate“issue“from“normal“public“useŽ¡‘0of–?ýan“object“library.‘ úClass“inheritance“can“be“a“powerful“implementation“technique,Ž¡‘0but–?ýextension“of“an“existing“class“framework“is“typically“safe“only“if“performed“inŽ¡‘0explicitly–?ýpermitted“ways.‘ úIf“a“library“supports“subclassing“at“all,“it“must“carefullyŽ¡‘0state–?ýwhich“classes“may“be“subclassed“and“in“what“ways.‘ úFor“a“library“module,“thisŽ¡‘0information–?ýis“supplied“outside“the“library“header“file.‘ úThe“library“header“fileŽ¡‘0specifies–?ýonly“the“interfaces“by“which“objects“are“intended“to“be“used,“whether“implementedŽ¡‘0by–?ýa“local“class“or“an“external“subclass.Ž¦ïhtml:ï html:Ÿ (d‘0Remaining–?ýsections“of“this“document“explain“the“declarations“which“appear“in“a“libraryŽ¡‘0header–?ýfile,“and“end“with“a“suggested“structure“of“documentation“to“be“provided“forŽ¡‘0a–?ýlibrary“module.‘ úThe“library“modules“of“Swarm“mostly“follow“this“structure.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ¨öÅObject–™™T‘þï5ype“DenitionsŽŸ¿The–?ýinterfaces“to“objects“defined“by“a“library“module“are“specified“by“object“type“definitions.Ž¡An–?ýobject“type“defines“only“a“set“of“messages“which“may“be“sent“to“an“object“over“various“phasesŽ¡of–?ýits“lifetime.‘ úAn“object“type“makes“no“commitment“to“the“classes“that“might“be“used“to“implementŽ¡the‘?ýobject.ŽŸ Ü»ïhtml:ï html:Ÿ (d‘0Multiple–?ýclasses“may“all“implement“the“same“messages“belonging“to“a“type.‘ úThe“independenceŽ¡‘0of–?ýtypes“and“classes“means“that“different“classes“can“provide“alternate“implementationsŽ¡‘0of–?ýthe“same“object“type.‘ úFor“example,“a“particular“implementing“class“might“be“selectedŽ¡‘0to–?ýoptimize“the“implementation“for“a“particular“case.Ž¦ïhtml:ï html:Ÿ (d‘0Object–?ýtypes“are“similar“to“protocols“defined“by“Objective“C,“and“the“declarationsŽ¡‘0appearing–?ýin“a“library“header“file“are“a“minor“adaptation“of“Objective“C“protocolŽ¡‘0syntax.‘ úA–?ýkey“difference“from“protocols“is“that“object“types“are“published“as“realŽ¡‘0external–?ýobjects“that“may“be“used“at“runtime“to“create“instances“of“a“type.‘ úA“futherŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹M-‚ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿difference–?ýis“that“the“object“types“of“the“defobj“library“are“divided“into“separateŽ¤‘/ºâinterfaces–?ýthat“define“distinct“phases“of“an“object's“life“cycle.ŽºâŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŸxÅGridT‘þ¬áurtle‘™™exampleŽŸÔ)¿An–?ýexample“will“help“illustrate“the“features“of“type“definitions“supported“by“the“defobj“library.Ž¡Throughout–?ýdocumentation“of“the“basic“Swarm“libraries,“a“series“of“running“examples“will“beŽ¡based–?ýon“a“simple“type“of“object“belonging“to“sample“Swarm“simulations.‘ úThis“type“of“objectŽ¡is–?ýan“agent“that“move“around“on“a“two-dimensional“grid,“always“moving“in“a“current“directionŽ¡that–?ýit“maintains“internally.‘ úThis“agent“is“like“a“"turtle"“of“the“original“Logo“system,“exceptŽ¡that–?ýits“position“is“constrained“to“discrete“integer“values“of“its“X-Y“coordinates,“and“itsŽ¡direction–?ýis“always“one“of“the“four“orthogonal“directions“north,“east,“south,“or“west.ŽŸ Ü»ïhtml:ï html:Ÿ ÷n‘0Following–?ýis“a“complete“library“header“file“for“a“module“which“defines“such“an“object,Ž¡‘0called‘?ýGridTurtle:Ž¤ïhtml:ï html:¡ïhtml:ï html:¤0R‘0Â/*Ž¡‘0Name:‘0™–GridTurtle.hŽ¡‘0Description:‘ ÌÌobject–fftype“for“Swarm“example“programsŽ¡‘0Library:‘ fdgridŽ¡‘0*/Ž¡¡‘0#import‘ffŽ¡‘0@deftype–ffGridTurtle“CREATINGŽ¡‘0-–ff(void)“setXLocMax:“(int)xLocMax;Ž¡‘0-–ff(void)“setYLocMax:“(int)yLocMax;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setXLoc:“(int)xLoc;Ž¡‘0-–ff(void)“setYLoc:“(int)yLoc;Ž¡‘0-–ff(void)“setXLoc:“xLoc“setYLoc:“yLoc;Ž¡¡‘0-–ff(void)“setDirection:“direction;Ž¡‘0USINGŽ¡‘0-–ff(int)“getXLoc;Ž¡‘0-–ff(int)“getYLoc;Ž¡¡‘0-‘ffgetDirection;Ž¡¡‘0-–ff(void)“move:“(int)distance;Ž¡‘0-–ff(void)“turn:“(int)angle;‘ ÌÌ//“angle“measured“in“units“of“pi/2“(90“deg.)Ž¡‘0-–ff(void)“print;Ž¡‘0@endŽ¡¡‘0id–ff“North,“East,“South,“West;Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹N= “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ#import‘ff"grid.xt"Ž©È%ºâ¿An–?ýobject“type“is“defined“by“an“@deftype“declaration.‘ úThe“syntax“of“such“declaration“is“identicalŽ¤ºâto–?ýthat“of“an“Objective“C“@protocol“definition,“except“for“the“entirely“uppercase“keywordsŽ¡ºâ(CREATABLE,–?ýCREATING,“SETTING,“USING)“appearing“in“the“GridTurtle“example“above.‘ úAll“theseŽ¡ºâmodifications–?ýof“Objective“C“syntax“are“accomplished“by“simple“preprocessor“macros;“no“extensionsŽ¡ºâto–?ýthe“language“compiler“are“involved.ŽºâŸ8äïhtml:ï html:Ÿ A‘0When–?ýthis“library“header“file“is“processed“(by“a“special“rule“in“a“make“file),“anŽ¡‘0external–?ýobject“id“with“the“name“GridTurtle“is“automatically“published.‘ úThe“nameŽ¡‘0of–?ýa“defined“type“becomes“an“ordinary“object“that“accepts“specific“messages“definedŽ¡‘0by–?ýthe“defobj“library.‘ úThe“ïhtml:ï html:defobj“libraryïhtml:ï html:Ž¦‘0(../defobj.html)Ž¦‘0explains–?ýthe“details“of“such“messages;“the“only“purpose“here“is“to“explain“the“basicŽ¡‘0sections–?ýof“a“deftype“declaration.Ž©8äïhtml:ï html:Ÿ A‘0deftype–?ýdeclarations“follow“the“syntax“as“Objective“C“protocols“for“inheriting“messagesŽ¡‘0from–?ýeach“other:‘ úa“list“of“names“enclosed“in“angle“brackets“(e.g.,“–?ýabove)“gives“the“names“of“other“declared“types“containing“messages“to“be“supportedŽ¡‘0by–?ýthe“new“type“as“well.‘ ú(These“types“referenced“here“are“defined“by“the“importedŽ¡‘0file–?ý.)‘ úLike“protocols,“full“multiple“inheritance“of“types“is“supported.Ž¡‘0The–?ýsame“messages“may“be“inherited“any“number“of“times“through“any“path“with“no“differentŽ¡‘0effect–?ýthan“if“inherited“or“declared“just“once,“so“long“as“no“conflicts“occur“in“anyŽ¡‘0of–?ýtheir“argument“or“return“types.Ž¦ïhtml:ï html:Ÿ A‘0The–?ýCREATABLE“tag“appearing“in“the“inherited“type“list“above“is“a“special“type“whichŽ¡‘0defines–?ýno“messages“of“its“own,“but“merely“marks“the“type“as“one“which“supports“directŽ¡‘0creation–?ýof“instances“of“the“type.‘ úWithout“this“tag,“the“only“role“of“a“type“is“toŽ¡‘0define–?ýmessages“for“inheritance“by“other“types.‘ úWith“this“tag,“the“global“type“objectŽ¡‘0has–?ýa“particular“implementation“that“supports“object“creation“using“standard“messagesŽ¡‘0defined–?ýin“defobj.Ž¦ïhtml:ï html:Ÿ A‘0The–?ýdeclared“messages“of“the“type“may“be“separated“into“sections“marked“by“the“specialŽ¡‘0uppercase–?ýtags“such“as“CREATING,“SETTING,“and“USING“above.‘ ú(Currently,“these“areŽ¡‘0the–?ýonly“such“tags“which“may“occur.)‘ úThese“sections“each“define“messages“belongingŽ¡‘0to–?ýa“particular“defined“"interface"“of“the“object“type,“which“are“further“combinedŽ¡‘0into–?ýdistinct“"phases"“of“an“object“lifecycle“supported“by“defobj“messages.‘ úFurtherŽ¡‘0explanation–?ýof“the“interfaces“and“phases“defined“by“this“example“are“provided“in“theŽ¡‘0ïhtml:ï html:Usage‘?ýGuideïhtml:ï html:Ž¤È%‘0(guide.html)Ž¡‘0of–?ýthe“defobj“library.Ž¦ïhtml:ï html:Ÿ A‘0The–?ýfollowing“line“at“the“end“of“the““header“file“above“is“required“as“partŽ¤‘0of–?ýthe“standard“conventions“for“coding“a“module“header“file:‘ úThis“line“adds“no“informationŽ¡‘0to–?ýthe“header“file,“but“is“required“as“part“of“the“system“by“which“definitions“areŽ¡‘0automatically‘?ýgenerated.Ž¦ïhtml:ï html:Ÿ A‘0Â#import‘ff"grid.xt"ŽŸbÌïhtml:ï html:Ÿ4‘0„¤ŽŽŸffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹OEÉ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅGlobal–™™Object“SymbolsŽŸùÛºâ¿The–?ý“header“file“above“also“contains“the“declaration:ŽºâŸ Ü»ïhtml:ï html:© ‘0Âid–ff‘ ÌÌNorth,“East,“South,“West;ŽŸV¿Lines–?ýthat“declare“global“id“variables“of“type“Symbol,“EventType,“Warning,“or“Error“(usingŽ¤the–?ýangle“bracket“syntax“of“id“variables“conforming“to“a“protocol)“are“processed“somewhat“likeŽ¡deftype–?ýdeclarations“in“that“they“also“produce“global“id“variables“initialized“to“support“particularŽ¡messages–?ýdefined“by“defobj.‘ úThese“global“variables,“however,“are“not“used“to“define“or“implementŽ¡other–?ýmessage“interfaces,“but“only“to“define“certain“fixed“capabilities“referenced“throughŽ¡their–?ýglobal“object“names.ŽŸ8äïhtml:ï html:¦‘0If–?ýdeclared“as“a“Symbol,“as“in“the“case“here,“the“generated“objects“have“no“particularŽ¡‘0behavior–?ýof“their“own“(other“than“the“character“string“of“their“name),“but“only“serveŽ¡‘0to–?ýdefine“unique“global“id“constants“which“may“be“used“as“distinct“named“values“inŽ¡‘0messages.‘ úIn–?ýthis“example,“the“current“direction“of“a“GridTurtle“object“is“representedŽ¡‘0by–?ýone“of“the“symbol“names“North,“East,“South,“or“West.‘ úThese“values“are“like“theŽ¡‘0enum–?ýconstants“of“the“C“language,“except“that“they“are“defined“as“full“Objective“CŽ¡‘0objects,–?ýand“may“be“used“with“further“restrictions.‘ úAn“EventType,“or“a“Warning“orŽ¡‘0Error,–?ýdefines“a“further“subtype“of“a“Symbol“constant“with“further“specialized“messagesŽ¡‘0documented–?ýin“defobj.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ²ÅInterface–™™Design“Con‘ÿl”vÛ$entionsŽŸùÛ¿A–?ývariety“of“rules“on“naming“and“declaration“of“object“types,“symbols,“and“messages“are“followedŽ¡by–?ýmany“of“the“Swarm“libraries.‘ úThese“rules“help“establish“a“basic“consistency“on“the“libraryŽ¡interfaces.‘ úFollowing–?ýis“a“list“of“such“conventions“that“apply“to“a“public“library“interface,Ž¡some–?ýbut“not“all“of“which“are“derived“from“standard“Smalltalk“or“Objective“C“coding“practice:ŽŸ Ü»ïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:¿Names–?ýof“global“object“constants“are“capitalized.‘ úIn“the“public“interface,“suchŽ¡‘:names–?ýinclude“types“and“symbols.ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:¿Recapitalization–?ýseparates“words“of“a“compound“name“(e.g.,“GridTurtle).‘ úUnderscoresŽ¡‘:are–?ýgenerally“not“used.ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:¿Message–?ýnames“start“with“a“lower-case“character,“and“are“named“using“verbs.‘ úNounsŽ¡‘:that–?ýrepresent“gettable“or“settable“components“of“object“state“(e.g.,“DirectionŽ¡‘:of–?ýa“GridTurtle),“are“prefixed“by“get“or“set“to“indicate“the“action“being“performed.ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:¿The–?ýSmalltalk“convention“that“a“message“return“the“receiver“of“a“message“if“thereŽ¡‘:is–?ýno“other“specific“return“value“is“generally“*not*“followed.‘ úIf“there“is“no“specificŽ¡‘:return–?ývalue“needed“from“a“message“the“return“type“is“declared“(void).ŽŸ‘0„¤ŽŽŸffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹PTÈ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅDocumentation‘™™Structur½«eŽŸÕ”ºâ¿The–?ýfollowing“standard“sections“of“documentation“are“suggested“for“libraries“that“follow“theŽ¤ºâstrict–?ýinterface“vs.‘ úimplementation“separation“of“library“modules,“each“with“purpose“and“typicalŽ¡ºâcontents–?ýas“given:ŽºâŸ Ü»ïhtml:ï html:Ÿ ïhtml:ï html:©ïhtml:ï html:Ÿ øÙ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface‘?ýReferenceŽž¬ïhtml:ï html:Ÿ‘:Complete,–?ýconcise“summary“of“all“features“of“a“library.‘ úFills“the“role“a“Unix“"manŽ¡‘Hpage"–?ýin“providing“comprehensive“definition“of“library“services.‘ úLittle“or“noŽ¡‘Hconcern–?ýto“provide“path“of“tutorial“introduction.‘ úDoes“not“contain“extendedŽ¡‘Hexamples,–?ýat“most“only“fragments“of“examples“which“serve“needs“of“specification.Ž¤8äïhtml:ï html:¦ïhtml:ï html:© øÙ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Usage‘?ýGuideŽ¡ïhtml:ï html:¦‘:Tutorial–?ýintroduction“to“a“library.‘ úFocuses“on“the“most“common“uses“in“an“orderŽ¤‘Hreflecting–?ýthe“needs“of“a“first-time“user.‘ úMost“explanation“by“means“of“progressivelyŽ¡‘Helaborated–?ýexamples.‘ úServes“as“a“guided“tour“of“major“library“capabilities.Ž¡‘HNo–?ýattempt“at“reference-style“completeness.Ž¤8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Advanced–?ýUsage“NotesŽ¡ïhtml:ï html:¦‘:Continues–?ýoverview“of“all“significant“capabilities“of“a“library,“including“thoseŽ¤‘Hwhich–?ýmight“be“needed“by“advanced“users“customizing“or“extending“built-in“capability.Ž¡‘HProvides–?ýexamples“of“specialized“uses“extending“beyond“normal,“basic“usage,“butŽ¡‘Hstill–?ýusing“built-in“features“of“the“library“framework.‘ úHelps“to“simplify“theŽ¡‘HUsage–?ýGuide“by“providing“a“location“for“overflow“of“more“advanced“features.Ž¤8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Subclassing‘?ýNotesŽ¡ïhtml:ï html:¦‘:Documents–?ýthe“rules“for“writing“new“classes“which“subclass“from“classes“that“implementŽ¤‘Hthe–?ýlibrary.‘ úBecause“a“library“might“use“complex“combinations“of“classes“toŽ¡‘Himplement–?ýthe“range“of“behaviors“defined“by“its“types,“the“classes“in“a“libraryŽ¡‘Hare–?ýnot“automatically“usable“as“superclasses“of“user-defined“classes.‘ úEach“libraryŽ¡‘Hdocuments–?ýwhich“classes“are“available“for“use“as“superclasses,“and“the“specificŽ¡‘Hrules–?ýthat“must“be“followed“when“subclassing“from“these“classes.Ž¤8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface–?ýDesign“NotesŽ¡ïhtml:ï html:¦‘:Explains–?ýwhy“choices“were“made“the“way“they“were“in“the“design“of“the“public“interfaceŽ¤‘Hto–?ýa“library,“including“other“alternatives“considered.‘ úServes“as“a“"Rationale"Ž¡‘Hdocument–?ýfor“the“documented“interface.‘ úMay“include“historical“background“deliberatelyŽ¡‘Hleft–?ýout“of“the“preceding“sections.‘ úMay“also“include“references“to“other“work.Ž¤8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Implementation‘?ýNotesŽ¡ïhtml:ï html:¦‘:Explains–?ýthe“structure“of“classes“by“which“the“types“of“a“library“are“implemented.Ž¤‘HSummarizes–?ýthe“status“of“implementation“if“still“incomplete“and“lists“items“ofŽ¡‘Hpossible–?ýfuture“work.‘ úProvides“overview“and“high-level“structure“of“the“implementationŽ¡‘Hin–?ýwhatever“ways“would“best“guide“a“reader“of“implementation“source“code.‘ úMayŽ¡‘Halso–?ýdiscuss“tradeoffs“considered“along“with“references“to“related“or“supportingŽ¡‘Hwork.Žïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:Ÿ1½‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Qb¦ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¾(mailto:mgd@santafe.edu)ŽºâŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Rt% “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Cr |eate“Combination“MessagesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¿The–?ýcreate“phase“of“an“object“type“may“contain“messages“that“are“defined“simply“byŽ¡‘0identifying–?ýthem“as“a“combination“of“other“defined“messages.‘ úSuch“messages“are“referredŽ¡‘0to–?ýas“"create“combination“messages."“Typically,“such“messages“have“the“following“form:Ž©8äïhtml:ï html:Ÿïhtml:ï html:Ÿ Ç‘0Â-‘Vf`create:–ffaZone“setOption:“optionValue;Ž¡¿For–?ýthis“message“to“be“a“valid“create“combination“message,“the“object“type“must“already“haveŽ¡the–?ýcreate:› úand“setOption:˜messages“defined“(either“locally“or“by“inheritance).˜The“meaningŽ¡of–?ýthis“message“is“then“identical“to“the“following“sequence“(where“SomeType“is“the“name“ofŽ¡a–?ýtype“implementing“the“combination“message):Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ Ç‘0Â-‘32anObject–ff=“[SomeType“createBegin:“aZone];Ž¡‘0-‘32[anObject–ffsetOption:“optionValue];Ž¡‘0-‘32anObject–ff=“[anObject“createEnd];Ž¡¿Create–?ýcombination“messages“are“provided“as“a“convenience“for“commonly“used“options.‘ úSomeŽ¡combination–?ýmessages“also“have“their“own“custom“implementing“methods“so“that“creation“is“fasterŽ¡when–?ýusing“the“combination“message.‘ úAny“such“implementation,“however,“is“required“to“implementŽ¡the–?ýparts“of“the“combination“message“so“that“its“meaning“is“identical“to“the“results“that“wouldŽ¡be–?ýobtained“if“the“separate“parts“were“requested“in“separate“message.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Su_ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Global“P•Üortability“AssumptionsŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¿In–?ýa“pure“object-oriented“system“such“as“Smalltalk,“the“type“of“an“object“referenceŽ¡‘0(an–?ýobject“id“in“Objective“C)“is“the“only“fundamental“data“type“used“within“the“system.Ž¡‘0In–?ýa“hybrid“object“system“such“as“Objective“C,“both“object“id's“and“other“data“typesŽ¡‘0are–?ýused“together.‘ úThe“Swarm“libraries“make“some“basic“assumptions“about“the“compatibilityŽ¡‘0of–?ýnative“C“data“types“with“the“id“pointer“type“of“Objective“C.“These“assumptionsŽ¡‘0allow–?ýsome“of“the“more“generic“abstractions“of“the“libraries“(such“as“collectionsŽ¡‘0and–?ýactions)“to“provide“one“fundamental“abstraction“that“can“still“be“used“under“anŽ¡‘0identical–?ýimplementation“to“support“most“of“the“other“C“data“types.Ž©8äïhtml:ï html:Ÿ Ç‘0The–?ýbasic“assumption“is“that“all“data“types“except“double“may“be“cast“to“and“fromŽ¡‘0a–?ýstored“id“type“without“losing“the“original“value.‘ úThis“assumption“is“valid“on“allŽ¡‘0modern–?ý32-bit“or“greater“machines,“including“all“machines“on“which“Swarm“is“currentlyŽ¡‘0running–?ýor“planning“to“run.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹T}¨ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Global“DenitionsŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ@¥ÀContentsŽŸâp¿The–?ýfollowing“global“definitions“are“documented“below:ŽŸ—ïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:¤ KW‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿M()‘?ýmacroïhtml:ï html:Ž©ÕSïhtml:ï html:Ÿ®è‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿func_t–?ýtype“definitionïhtml:ï html:ŽŸ8äïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿initModule()‘?ýmacroïhtml:ï html:Ž¦ïhtml:ï html:Ÿ®è‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿global‘?ýzonesïhtml:ï html:Ž©8äïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿output‘?ýfilesïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿debug‘?ýsupportïhtml:ï html:ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ@¥ÀM()‘Qëmacr°goŽŸM‹ïhtml:ï html:ŸäÄÅSynopsisŽŸ‘ýïhtml:ï html:Ÿ –‘0Â//Ž¤„;‘0//–ffM()“--“macro“to“abbreviate“@selector()Ž¡‘0//Ž¡‘0#define–ffM(“messageName“)‘ ÌÌ@selector(“messageName“)Ž¡¿The–?ýM()“macro“is“currently“nothing“more“than“an“abbreviation“for“the“Objective“C“syntax“usedŽ¤to–?ýobtain“a“selector“for“a“particular“message“name.‘ úIt“is“provided“as“a“convenience“for“useŽ¡in–?ýmessages“that“combine“a“selector“with“other“arguments.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ@¥Àfunc_t–Qëtype“denitionŽŸê”ïhtml:ï html:ŸG»ÅSynopsisŽŸ‘ýïhtml:ï html:Ÿ –‘0Â//Ž¤„;‘0//–fffunc_t“--“function“pointer“typeŽ¡‘0//Ž¡‘0typedef–ffvoid“(*func_t)(“void“);ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹U„‡ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿func_t–?ýprovides“a“type“definition“for“a“generic“function“pointer“type“(taking“no“argumentsŽ¤ºâand–?ýreturning“no“value).‘ úThis“type“name“is“used“in“declaring“messages“that“accept“or“returnŽ¡ºâfunction–?ýpointers“of“various“alternative“types.Žºâ©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¾ÀinitModule()‘QëfunctionŽŸM‹ïhtml:ï html:ŸbžÅSynopsisŽŸ‘ýïhtml:ï html:Ÿ ï‘0Â//Ž¤ ‘0//–ffinitModule()“--“module“initialization“macroŽ¡‘0//Ž¡‘0#define–ffinitModule(“module“)Ž¡¿The–?ýinitModule“function“must“be“called“to“initialize“all“the“definitions“of“a“library“moduleŽ¤before–?ýany“attempt“is“made“to“use“the“library.‘ úInitializing“a“particular“library“module“willŽ¡also–?ýinitialize“all“other“library“modules“on“which“the“library“depends.‘ úThe“macro“has“no“effectŽ¡if–?ýthe“library“has“already“been“initialized,“so“that“multiple“libraries“that“all“depend“onŽ¡another–?ýlibrary“can“all“request“initialization“of“the“other“library“with“no“ill“effect.‘ úTheŽ¡argument–?ýof“the“macro“is“the“name“of“module“to“be“initialized.‘ úFor“example,“if“just“the“collectionsŽ¡library–?ýwere“being“initialized,“the“macro“would“be“coded:Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¾ÀGlobal‘QëZonesŽŸªóïhtml:ï html:Ÿ6ÅSynopsisŽŸ‘ýïhtml:ï html:Ÿ ï‘0Â#define‘ffglobalZoneŽ¤ ‘0#define‘ffscratchZoneŽ¡¿The–?ýidentifiers“globalZone“and“scratchZone“refer“to“two“standard“zones“created“by“initializationŽ¤of–?ýthe“defobj“library.‘ úAll“other“created“zones“must“obtain“their“storage“from“one“or“the“otherŽ¡of–?ýthese“two“initial“zones.‘ ú(These“initial“zones“are“defined“as“macros“only“to“follow“conventionsŽ¡on–?ýglobal“external“names.)Ž¦ïhtml:ï html:Ÿ É1‘0globalZone–?ýmay“be“used“for“all“storage“which“must“be“allocated“for“the“duration“ofŽ¡‘0the–?ýprogram,“or“until“explicitly“released.‘ úscratchZone“should“be“used“for“storageŽ¡‘0which–?ýis“allocated“only“for“use“during“execution“of“a“single“function.‘ úIt“is“typicallyŽ¡‘0used–?ýfor“objects“which“are“strictly“temporary“as“part“of“a“local“computation.‘ ú(..Ž¡‘0Currently,–?ýa“scratch“zone“has“the“identical“implementation“as“the“global“zone,“butŽ¡‘0eventually–?ýa“scratch“zone“may“be“optimized“for“temporary“allocations,“and“such“allocationsŽ¡‘0may–?ýalso“be“freed“automatically“at“various“points“when“functions“are“guaranteed“toŽ¡‘0be‘?ýcomplete.)Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹V® “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâ©G®ïhtml:ï html:Ÿ ŽÀOutput‘QëFilesŽŸê”ïhtml:ï html:Ÿ¤ÅSynopsisŽŸ‘ýïhtml:ï html:Ÿ ^þ‘0Âextern–ffFILE“*_obj_xerror;‘ÿþ//“output“file“for“error“messagesŽ¤M$‘0extern–ffFILE“*_obj_xdebug;‘ÿþ//“output“file“for“debugging“messagesŽ¡¿The–?ýfile“pointers“_obj_xerror“and“_obj_xerror“define“standard“output“files“used“for“error“messagesŽ¤and–?ýdebugging“messages,“respectively.‘ úIf“not“set“otherwise“by“the“time“of“defobj“module“initialization,Ž¡they–?ýboth“default“to“the“standard“error“output“defined“by“the“C“library.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:Ÿ ŽÀDeb§Œug‘QëSupportŽŸê”ïhtml:ï html:Ÿ¤ÅSynopsisŽŸ‘ýïhtml:ï html:Ÿ ^þ‘0Âextern–ffBOOL“_obj_debug;‘%ÌÊ//“if“true“then“perform“all“debug“error“check-Ž¡‘0ingŽ¤M$¡‘0extern–ffvoid“xsetname“(id“anObject,“const“char“*name);‘ ÌÌ//“debug“set“dis-Ž©‘0play‘ffnameŽ¡¡‘0extern–ffvoid“xprint“(id“anObject);‘K™”//“debug“object“printŽ¡‘0extern–ffvoid“xprintid“(id“anObject);‘@ÌÈ//“debug“object“id“printŽ¡¡‘0extern–ffvoid“xfprint“(id“anObject);‘F3.//“debug“foreach“object“printŽ¡‘0extern–ffvoid“xfprintid“(id“anObject);‘;fb//“debug“foreach“id“printŽ¡¡‘0extern–ffvoid“xexec“(id“anObject,“const“char“*name);‘ ÌÌ//“debug“method“execŽ¡‘0extern–ffvoid“xfexec“(id“anObject,“const“char“*name);“//“debug“fore-Ž¦‘0ach–ffmethod“execŽŸÉïhtml:ï html:Ÿ0[‘0¿The–?ý_obj_debug“variable“enables“debug-level“error“checking“in“libraries“that“supportŽ¦‘0optional–?ýlevels“of“checking.› úIts“default“value“is“true.˜The“default“may“be“overriddenŽ¦‘0either–?ýbefore“initialization“of“the“defobj“module,“or“by“means“of“a“compiler“macroŽ¦‘0setting–?ý(-D_obj_debug=0).‘ úIf“set“to“zero“by“a“compiler“macro“setting,“optimized“compilationŽ¦‘0of–?ýcode“that“refers“to“it“will“see“only“the“constant“zero“and“so“avoid“even“generatingŽ¦‘0code–?ýto“test“the“variable.ŽŸïhtml:ï html:¡‘0The–?ýxsetname“function“sets“the“display“name“for“an“object“using“its“setDisplayName:Ž¦‘0message.‘ úThis–?ýstring“may“be“used“to“identify“the“object“in“a“user-meaningful“way;Ž¦‘0if–?ýdefined“it“will“appear“in“the“identification“string“generated“by“a“standard“describe:Ž¦‘0message.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹W˜· “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0¿The–?ýxprint“function“prints“a“standard“object“description“to“the“standard“debuggingŽ¤‘0output–?ýfile.› úIt“generates“the“string“to“be“printed“using“the“describe:˜message“definedŽ¡‘0by–?ýthe“DefinedObject“supertype,“but“it“is“defined“as“a“function“so“that“it“may“beŽ¡‘0called–?ýdirectly“from“a“debugger.‘ úxprintid“is“similar,“but“it“prints“only“a“one-lineŽ¡‘0description–?ýusing“the“built-in“default.Ž©8äïhtml:ï html:Ÿ Ç‘0The–?ýxfprint“function“is“similar“to“the“xprint“function,“except“that“it“prints“a“debugŽ¡‘0description–?ýfor“each“member“of“a“collection.‘ úThe“argument“of“xfprint“must“supportŽ¡‘0enumeration–?ýof“collection“members“using“the“messages“of“the“ïhtml:ï html:Collectionïhtml:ï html:Ž¡‘0(../collections/Collection.html)Ž¡‘0type.‘ úxfprintid–?ýis“similar,“but“only“one“line“per“member“is“printed.Ž¦ïhtml:ï html:Ÿ Ç‘0The–?ýxexec“function“executes“a“message“on“an“object“passed“as“an“argument.‘ úThe“nameŽ¡‘0of–?ýmessage“to“be“executed“(the“full“name“including“arguments“as“would“be“used“in“namingŽ¡‘0a–?ýselector)“must“be“given“as“the“second“argument.‘ úThis“function“is“equivalent“toŽ¡‘0the–?ý"perform:"“message“of“Objective“C,“but“is“defined“as“a“function“so“that“it“mayŽ¡‘0be–?ýcalled“directly“from“a“debugger.Ž¦ïhtml:ï html:Ÿ Ç‘0The–?ýxfexec“function“is“similar“to“the“xexec“function,“except“that“it“executes“a“messageŽ¡‘0on–?ýeach“member“of“a“collection.‘ úThe“first“argument“of“xfprint“must“support“enumerationŽ¡‘0of–?ýcollection“members“using“the“messages“of“the“ïhtml:ï html:Collectionïhtml:ï html:Ž¡‘0(../collections/Collection.html)Ž¡‘0type.Ž¦ïhtml:ï html:Ÿ Ç‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹X¢Ý “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Subclassing“Refer |enceŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¿The–?ýdefobj“library“currently“includes“the“CreateDrop“and“Object_s“superclasses“usedŽ¡‘0by–?ýother“libraries.‘ úFor“user“objects“in“Swarm“simulations“the“SwarmObject“superclassŽ¡‘0in–?ýthe“ïhtml:ï html:objectbaseïhtml:ï html:Ž¡‘0(../objectbase.html)Ž¡‘0library–?ýpackages“all“required“behavior“of“these“superclasses“into“a“single,“simplerŽ¡‘0superclass.Ž©8äïhtml:ï html:Ÿ Ç‘0The–?ýdefobj“library“also“provides“support“for“custom-generated“classes,“such“as“thoseŽ¡‘0which–?ýimplement“separate“phases“of“the“standard“create“protocol.‘ ú(See“ïhtml:ï html:generated“phaseŽ¡‘0classesïhtml:ï html:Ž¡‘0(adv.html#phase-classes)Ž¡‘0in–?ýthe“ïhtml:ï html:Advanced“Usage“Guideïhtml:ï html:Ž¡‘0(adv.html)Ž¡‘0.)‘ úSubclassing–?ýfrom“custom-generated“classes“is“still“not“officially“supported,“becauseŽ¡‘0the–?ýframework“for“custom“class“generation“is“still“being“finalized.‘ úCustom-generatedŽ¡‘0classes–?ýare“currently“used“only“in“the“defobj,“collections,“and“activity“libraries;Ž¡‘0these–?ýlibraries“document“the“specific“classes“that“provide“subclassing“support.Ž¦ïhtml:ï html:Ÿ Ç‘0In–?ýgeneral,“classes“that“implement“a“library“are“not“automatically“available“for“useŽ¡‘0as–?ýsuperclasses.‘ úAny“library“must“document“those“specific“superclasses“that“are“validŽ¡‘0for–?ýuser“classes“to“subclass“from,“along“all“the“rules“that“a“user“subclass“must“followŽ¡‘0when–?ýimplementing“new“behavior.Ž¦ïhtml:ï html:Ÿïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Y«Å “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Interface“Design“NotesŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:©‘0¿(This–?ýsection“of“documentation“is“not“yet“available.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¡ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Z´Á “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Implementation“NotesŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:©‘0¿(This–?ýsection“of“documentation“is“not“yet“available.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¡ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹[· “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Collections‘/LibraryŽŸq'‘0„¤ŽŽ¤ïhtml:ï html:ŸžL‘0ÊDocumentation–and“Implementation“StatusŽŸ‘0„¤ŽŽ©G®ïhtml:ï html:ŸôPÀOv•ÓÅer“viewŽŸ–¿The–?ýobject“types“of“the“collections“library“establish“a“general-purpose“foundation“to“maintainŽ¡object–?ýreferences“or“other“values“as“members“of“structured“collections.‘ úCustomization“optionsŽ¡consolidate–?ýa“wide“range“of“basic“collection“structures“into“a“few“core“types“(Array,“List,Ž¡Set,–?ýMap).‘ úThese“types“are“defined“strictly“by“their“interface,“not“their“internal“implementation.Ž¡Specialized–?ýoptions,“however,“give“control“and“flexibility“for“efficient,“low-level“use“(suchŽ¡as–?ýimplementing“other“libraries).ŽŸ—ïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:ŸôPÀDocumentationŽ¤–¿The–?ýcollections“library“follows“the“ïhtml:ï html:library“definition“conventionsïhtml:ï html:Ž¡(defobj/library.html)Ž¤7æ.‘ úIt–?ýhas“following“standard“sections“of“documentation:Ž©8äïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:Ÿ ÿ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Usage‘?ýGuideïhtml:ï html:Ž¡‘0(collections/guide.html)Ž¦ïhtml:ï html:Ÿ ÿ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Advanced–?ýUsage“Guideïhtml:ï html:Ž¡‘0(collections/adv.html)ŽŸ ÕSïhtml:ï html:Ÿïhtml:ï html:©b“‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface‘?ýReferenceïhtml:ï html:Ž¡‘0(collections/ref.html)ŽŸÕSïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Subclassing‘?ýReferenceïhtml:ï html:Ž¡‘0(collections/subclass.html)ŽŸ ÕSïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface–?ýDesign“Notesïhtml:ï html:Ž¡‘0(collections/design.html)ŽŸ8äïhtml:ï html:© ÿ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Implementation‘?ýNotesïhtml:ï html:Ž¡‘0(collections/impl.html)ŽŸ8äïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹\º[ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¾(mailto:mgd@santafe.edu)ŽºâŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹]ÅW “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Collections–/Library:‘m™Documentation“andŽŸâImplementation‘/StatusŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:©¤‘0¿The–?ýcollections“library“has“an“almost“complete“set“of“Interface“Reference“documents,Ž¤‘0and–?ýthe“design“of“the“interface“is“almost“entirely“final.‘ úThe“implementation“of“theŽ¡‘0collections–?ýlibrary,“however,“doesn't“yet“implement“many“of“the“more“advanced“featuresŽ¡‘0of–?ýthis“interface.ŽŸïhtml:ï html:¦‘0Collections–?ýlibrary“development“has“concentrated“on“the“specific“features“needed“byŽ¡‘0the–?ýactivity“library.‘ úThis“library“uses“collections“for“its“underlying“support“ofŽ¡‘0actions–?ýto“be“executed“in“schedules.‘ úThe“collections“library“itself“is“still“beingŽ¡‘0completed–?ýfor“use“as“a“general-purpose“library.Ž©8äïhtml:ï html:Ÿ ÎÀ‘0The–?ýArray“and“List“types“have“all“basic“capability“fully“implemented.‘ úSet“and“MapŽ¡‘0have–?ýbasic“messages“defined,“but“currently“rely“on“a“crude“implementation“based“onŽ¡‘0sorted–?ýlists.‘ ú(This“implementation“is“more“than“adequate“for“the“usually“small“andŽ¡‘0relatively–?ýstatic“schedule“structures“in“the“activity“library,“and“is“the“most“forgivingŽ¡‘0when–?ýchange“does“take“place“within“members“being“traversed.)‘ úMuch“more“efficientŽ¡‘0implementations–?ýbased“on“both“balanced“trees“and“hash“tables“are“in“the“works.Ž¦ïhtml:ï html:Ÿ ÎÀ‘0OrderedSet–?ýis“currently“supported“only“with“the“low-level“option“for“an“internal“memberŽ¡‘0slot,–?ýand“the“implemented“messages“do“not“match“the“ones“documented“in“the“InterfaceŽ¡‘0Reference.‘ úSupport–?ýfor“groups“of“duplicate“members“is“missing“from“both“Set“and“Map.Ž¦ïhtml:ï html:Ÿ ÎÀ‘0None–?ýof“the“special“options“for“restricted“usage“modes“on“any“type“of“collection“(e.g.,Ž¡‘0read-only–?ýrestriction)“has“been“implemented.‘ úStack“and“Queue“are“not“implemented,Ž¡‘0but–?ýare“nothing“more“than“restricted“uses“of“a“List.‘ úThere“is“no“support“for“anyŽ¡‘0member–?ýtype“except“id“or“smaller“(other“member“types“will“depend“on“a“data“type“facilityŽ¡‘0to–?ýbe“supplied“by“defobj).Ž¦ïhtml:ï html:Ÿ ÎÀ‘0Even–?ýthough“incomplete,“the“portion“of“capability“that“is“implemented“has“been“exercisedŽ¡‘0very–?ýheavily.‘ úThe“interfaces“to“Set“and“Map“structures“will“remain“the“same“evenŽ¡‘0as–?ýtheir“underlying“implementations“improve,“so“there“is“no“harm“in“using“them.‘ úSeeŽ¡‘0the–?ýïhtml:ï html:GridTurtle“test“programsïhtml:ï html:Ž¤¤‘0(../grid.html)Ž¡‘0for–?ýthe“most“complete“examples“of“collections“usage.Ž¦ïhtml:ï html:Ÿ ÎÀ‘0The–?ýcollections“library“follows“the“documentation“structure“suggested“by“the“ïhtml:ï html:libraryŽ©‘0interface‘?ýconventionsïhtml:ï html:Ž¡‘0(../defobj/library.html)Ž¡‘0of–?ýthe“defobj“library.‘ úThere“are“placeholders“at“least“for“each“section“of“documentationŽ¦‘0(some–?ýof“which“merely“indicate“that“the“section“is“not“available“yet)“so“that“allŽ¦‘0links–?ýshould“at“least“link“up“with“something,“whether“or“not“there's“anything“there.Ž¤8äïhtml:ï html:Ÿ ÎÀ‘0Throughout–?ýthe“documentation,“a“parenthesized“comment“that“starts“with“(..‘ úindicatesŽ¦‘0an–?ýeditorial“comment“on“the“current“status“of“implementation“or“documentation.Ž¡ïhtml:ï html:Ÿ ÎÀ‘0The–?ýdocumentation“priority“for“all“libraries“is“to“complete“at“least“their“interfaceŽ¦‘0reference–?ýdocuments,“so“that“there“is“the“equivalent“of“Unix“"man“pages"“that“summarizeŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹^Æ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿all–?ýbasic“capability.‘ úA“second“priority“is“to“complete“the“complementary“"Usage“Guide"Ž¤‘/ºâdocuments.‘ úUnlike–?ýthe“reference“documents,“the“Usage“Guide“will“have“a“task-orientedŽ¡‘/ºâorganization,–?ýand“will“lead“the“initial“user“through“actual“code“examples“in“the“roughŽ¡‘/ºâorder–?ýa“typical“user“is“likely“to“need“them.‘ úIt“will“serve“the“role“of“a“tutorialŽ¡‘/ºâon–?ýeach“library.Žºâ©8äïhtml:ï html:Ÿ Ç‘0The–?ýUsage“Guide“code“examples“have“not“yet“been“developed.‘ úFor“the“time“being,“aŽ¡‘0directory–?ýof“test“programs“(ïhtml:ï html:GridTurtle“test“programsïhtml:ï html:Ž¡‘0(../grid.html)Ž¡‘0,–?ýcontained“within“the“documentation“release“directory)“provides“code“examples“ofŽ¡‘0many–?ýof“the“basic“features“of“the“defobj,“collections,“and“activity“libraries.‘ úTheseŽ¡‘0code–?ýexamples“also“help“indicate“the“portions“of“the“libraries“which“are“fully“implementedŽ¡‘0and–?ýworking,“since“they“are“run“on“each“new“release“of“these“libraries.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹_Õð “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Collections–/Library:‘m™Usage“GuideŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤‘0¿This–?ýsection“of“documentation“is“not“yet“available.‘ úIn“the“meantime,“see“the“ïhtml:ï html:GridTurtleŽ¡‘0test‘?ýprogramsïhtml:ï html:Ž¡‘0(../grid.html)Ž¡‘0for–?ýthe“most“complete“examples“of“collections“library“usage.‘ úIf“you“can't“find“anŽ¡‘0example–?ýthere“that“exercises“a“message“or“option“that“you“want“to“use,“chances“areŽ¡‘0it's–?ýnot“implemented.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹`Ü “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Collections–/Library:‘m™AdvÊìanced“Usage“GuideŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:©‘0¿(This–?ýsection“of“documentation“is“not“yet“available.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¡ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹aà= “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Collections–/Library:‘m™Interface“Refer |enceŽŸq'‘0„¤ŽŽ©G®ïhtml:ï html:ŸýÀDependenciesŽŸŸJ¿Following–?ýare“the“other“header“files“imported“by“:ŽŸ—ïhtml:ï html:Ÿïhtml:ï html:Ÿ 1‘0Â#import‘ffŽ¤A¿The–?ýcollections“library“follows“the“ïhtml:ï html:library“interface“conventionsïhtml:ï html:Ž¡(../defobj/library.html)Ž¡of–?ýthe“ïhtml:ï html:defobj“libraryïhtml:ï html:Ž¡(../defobj.html)Ž¡.› úIt–?ýalso“depends“on“standard“supertypes“and“classes“defined“by“this“library.˜InitializationŽ¤of–?ýthe“collections“library“automatically“initializes“the“defobj“library“as“well.‘ úSince“defobjŽ¡also–?ýrequires“the“collections“library,“both“must“always“be“linked“into“an“application“together.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:ŸýÀObject–QëT‘þ¸¦ypes“(with“links“to“r•°gefer“ence‘Qëpages)ŽŸ âcïhtml:ï html:ïhtml:ï html:Ÿ¼ç‘0ÂCollectionïhtml:ï html:Ž¤A‘5ff(Collection.html)Ž¡‘eÿüïhtml:ï html:Stringïhtml:ï html:Ž¡‘5ff(String.html)Ž¡‘Pfdïhtml:ï html:OutputStreamïhtml:ï html:Ž¡‘5ff(Stream.html)Ž¡‘@32ïhtml:ï html:Indexïhtml:ï html:Ž¡‘5ff(Index.html)Ž¡¡‘Jÿþ/‘%ÌÊ|‘0™–\Ž¡‘E™˜/‘+30|‘5ÿü\Ž¡‘5ffïhtml:ï html:Arrayïhtml:ï html:Ž¡‘5ff(Array.html)Ž¡‘Jÿþïhtml:ï html:List,ïhtml:ï html:Ž¡‘5ff(List.html)Ž¡‘kfbïhtml:ï html:KeyedCollection,ïhtml:ï html:Ž¡‘5ff(KeyedCltn.html)Ž¡¡‘v3.ïhtml:ï html:ListIndexïhtml:ï html:Ž¡‘5ff(List.html)Ž¡‘UÌÊïhtml:ï html:KeyedIndexïhtml:ï html:Ž¡‘5ff(KeyedCltn.html)Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹bã “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘?îÂ/‘%ÌÊ\‘+30/‘;fb\ŽºâŸ¸Mïhtml:ï html:ŸT ‘0Stackïhtml:ï html:Ž¤V‘5ff(Stack.html)Ž¡‘E™˜ïhtml:ï html:Queueïhtml:ï html:Ž¡‘5ff(Stack.html)Ž¡‘E™˜ïhtml:ï html:Set,ïhtml:ï html:Ž¡‘5ff(Set.html)Ž¡‘`™–ïhtml:ï html:Map,ïhtml:ï html:Ž¡‘5ff(Map.html)Ž¡¡‘pÌÈïhtml:ï html:SetIndexïhtml:ï html:Ž¡‘5ff(Set.html)Ž¡‘Jÿþïhtml:ï html:MapIndexïhtml:ï html:Ž¡‘5ff(Map.html)Ž¡¡’Ç3(|Ž¡‘eÿüïhtml:ï html:OrderedSetïhtml:ï html:Ž¡‘5ff(OrderedSet.html)Ž¡¿(need–?ýa“graphic“with“image“map,“but“this“will“do“for“now)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:ŸÈÀÀContents:ŽŸ ¢Âïhtml:ï html:Ÿïhtml:ï html:ŸÇÉ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Collectionïhtml:ï html:Ž¡‘0(Collection.html)Ž©ÕSïhtml:ï html:Ÿ7‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Indexïhtml:ï html:Ž¡‘0(Index.html)Ž¦ïhtml:ï html:Ÿ7‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Arrayïhtml:ï html:Ž¡‘0(Array.html)ŽŸ8äïhtml:ï html:Ÿ Ór‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Listïhtml:ï html:Ž¡‘0(List.html)Ž¦ïhtml:ï html:Ÿ7‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Stackïhtml:ï html:Ž¡‘0(Stack.html)Ž¦ïhtml:ï html:Ÿ7‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Queueïhtml:ï html:Ž¡‘0(Stack.html)Ž¦ïhtml:ï html:Ÿ7‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿KeyedCollectionïhtml:ï html:Ž¡‘0(KeyedCltn.html)ŽŸ8äïhtml:ï html:Ÿ Ór‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Setïhtml:ï html:Ž¡‘0(Set.html)Ž¦ïhtml:ï html:Ÿ7‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿OrderedSetïhtml:ï html:Ž¡‘0(OrderedSet.html)Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹cëÇ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâïcolor push BlackÁlï color popŽŽ‘9ºâïhtml:ï html:¿Mapïhtml:ï html:Ž¤‘/ºâ(Map.html)Žºâ©8äïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Stringïhtml:ï html:Ž¡‘0(String.html)Ž¦ïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿OutputStreamïhtml:ï html:Ž¡‘0(Stream.html)ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹döX “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸœýÅCollection–™™-“supertype“of“all“collection“typesŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸVFÀSynopsisŽŸ âcïhtml:ï html:Ÿ ®‘0Â//Ž¤™Ü‘0//–ffCollection“--“supertype“of“all“collection“typesŽ¡‘0//Ž¡‘0@deftype–ffCollection“CREATINGŽ¡‘0-–ff(void)“setMemberType:“aDataType;Ž¡‘0-–ff(void)“setIndexSafety:“indexSafety;Ž¡‘0-–ff(void)“setIndexUpdateHandler:“(func_t)handler“:“(void“*)arg;Ž¡‘0-–ff(void)“setReplaceOnly:“(BOOL)replaceOnly;Ž¡‘0USINGŽ¡‘0-‘ffgetMemberType;Ž¡‘0-‘ffgetIndexSafety;Ž¡‘0-–ff(func_t)“getIndexUpdateHandler:“(void“*)arg;Ž¡‘0-–ff(BOOL)“getReplaceOnly;Ž¡¡‘0-–ff(int)“getCount;Ž¡¡‘0-–ffatOffset:“(int)offset;Ž¡‘0-–ffatOffset:“(int)offset“put:“anObject;Ž¡¡‘0-‘ffgetFirst;Ž¡‘0-‘ffgetLast;Ž¡¡‘0-–ff(BOOL)“contains:“aMember;Ž¡‘0-–ffremove:“aMember;Ž¡‘0-–ff(void)“removeAll;Ž¡¡‘0-–ffbegin:“aZone;Ž¡¡‘0-–ff(void)“forEach:“(SEL)aSelector;Ž¡‘0-–ff(void)“forEach:“(SEL)aSelector“:“arg1;Ž¡‘0-–ff(void)“forEach:“(SEL)aSelector“:“arg1“:“arg2;Ž¡‘0-–ff(void)“forEach:“(SEL)aSelector“:“arg1“:“arg2“:“arg3;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŽŸ*ºâïcolor push BlackŽŽŽŽŽ’Ôï color popŽŽŒ‹eú “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÑçåºâÀDescriptionŽŸ7 ºâ¿A–?ýcollection“is“a“grouping“of“object“references“or“other“data“values“which“are“assigned“explicitlyŽ¤ºâas–?ýmembers“of“the“collection.‘ úDepending“on“the“subtype,“collection“members“may“also“be“maintainedŽ¡ºâin–?ývarious“associations“with“each“other,“such“as“an“ordering“of“members“or“an“association“ofŽ¡ºâmembers–?ýwith“identifying“key“values.‘ úMajor“Collection“subtypes“include“Array,“List,“Set“andŽ¡ºâMap.‘ úThe–?ýCollection“supertype“establishes“common“conventions“(and“associated“messages)“supportedŽ¡ºâby–?ýall“types“of“collections.ŽºâŸ—ïhtml:ï html:©Ÿñ‘0All–?ýcollections“support“traversal“over“their“members“using“a“separate“object“calledŽ¡‘0an–?ýIndex.‘ úAll“collections“also“follow“common“rules“regarding“the“types“of“data“valuesŽ¡‘0which–?ýmay“be“added“as“members.‘ úThe“next“two“subsections“summarize“these“basic“featuresŽ¡‘0of–?ýall“collections.ŽŸïhtml:ï html:Ÿffïhtml:ï html:Ÿ ƒÅIndex‘™™objectsŽŸ|¬¿An–?ýindex“is“a“special“type“of“object“that“references“a“current“position“in“an“enumeration“sequenceŽ¡over–?ýa“collection.‘ úAn“enumeration“sequence“contains“every“member“of“a“collection“exactly“once.Ž¡Every–?ýcollection“defines“an“associated“type“of“object“for“its“index.‘ úThe“index“type“of“a“collectionŽ¡defines–?ýadditional“ways“in“which“the“members“of“a“collection“may“be“processed“beyond“any“messagesŽ¡available–?ýdirectly“on“the“collection.‘ úOften“the“operations“of“an“index“provide“the“most“basicŽ¡and–?ýflexible“means“for“manipulating“individual“members“of“a“collection.‘ úAn“index“object“intoŽ¡a–?ýcollection“may“be“created“at“any“time.‘ úAn“index“is“the“basic“means“to“traverse“through“allŽ¡members–?ýof“a“collection.‘ úMultiple“indexes“on“the“same“collection“may“all“exist“at“the“sameŽ¡time–?ýand“may“reference“the“same“or“different“positions.‘ úDepending“on“the“collection“type,Ž¡it–?ýmay“be“possible“to“modify“a“collection“through“its“indexes.ŽŸ Ü»ïhtml:ï html:¦‘0Once–?ýan“index“is“created,“the“sequence“of“members“in“its“enumeration“sequence“is“guaranteedŽ¡‘0to–?ýremain“the“same,“provided“that“no“new“members“are“added“to“the“underlying“collection,Ž¡‘0or–?ýexisting“members“removed.‘ úIf“a“member“is“located“once“at“a“particular“position,Ž¡‘0it–?ýis“guaranteed“to“remain“at“that“position“as“long“as“the“index“itself“remains.ŽŸ8äïhtml:ï html:¦‘0Many–?ýcollection“types“define“an“explicit“ordering“over“their“members.‘ úFor“such“collections,Ž¡‘0the–?ýsequence“of“members“referred“to“by“an“index“will“always“be“consistent“with“thisŽ¡‘0ordering.‘ úAn–?ýexplicit,“total“ordering“also“guarantees“that“all“indexes“of“the“sameŽ¡‘0collection–?ýhave“the“same“member“sequence.ŽŸ8äïhtml:ï html:¦‘0If–?ýno“such“ordering“is“defined,“however,“some“particular“sequence“of“all“the“collectionŽ¡‘0still–?ýbecomes“associated“with“each“created“index.‘ úAll“collection“members“are“guaranteedŽ¡‘0to–?ýbe“contained“somewhere“in“the“enumeration“sequence“for“any“particular“index,“butŽ¡‘0two–?ýindexes“on“the“same“collection“are“not“guaranteed“to“have“the“same“sequence.ŽŸ8äïhtml:ï html:¦‘0The–?ýIndex“type“corresponds“to“the“iterator“types“defined“as“part“of“many“other“object-orientedŽ¡‘0libraries.‘ úThe–?ýname“Index“is“shorter“and“emphasizes“the“more“abstract“and“multi-functionŽ¡‘0role–?ýof“these“basic“support“objects“for“any“collection.‘ úFor“more“background“on“designŽ¡‘0of–?ýindexes“and“iterators,“see“the“Interface“Design“Notes“for“the“collections“library.ŽŸ8äïhtml:ï html:Ÿffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹f “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅMember‘™™typesŽŸ,`ºâ¿The–?ýdefault“member“type“of“any“collection“is“the“id“type“defined“by“Objective“C.“All“messagesŽ¤ºâwhich–?ýadd,“remove,“or“access“members“declare“their“member“value“with“the“id“type.‘ úNone“ofŽ¡ºâthe–?ýcollection“types,“however,“requires“that“the“member“value“actually“point“to“a“valid“object.Ž¡ºâThe–?ýmember“values“of“any“collection“may“contain“an“arbritrary“bit“pattern,“provided“these“bitsŽ¡ºâfit–?ýin“the“space“available“within“an“id“pointer.ŽºâŸ Ü»ïhtml:ï html:© O¥‘0In–?ýthe“few“cases“when“default“operations“assume“that“a“member“points“to“a“valid“object,Ž¡‘0there–?ýare“alternate“ways“to“avoid“these“defaults“and“use“an“arbritrary“bit“patternŽ¡‘0as–?ýa“member“value“instead.‘ úWhen“using“an“arbritrary“bit“pattern,“the“member“valueŽ¡‘0must–?ýbe“cast“to“or“from“the“id“type“when“adding“or“retrieving“it“from“the“collection.Ž¡‘0By–?ýïhtml:ï html:global“portability“assumptionsïhtml:ï html:Ž¤ˆ‰‘0(../global-port.html)Ž¡‘0,–?ýthe“number“of“bits“in“an“id“value“may“be“safely“assumed“to“be“at“least“as“largeŽ¤‘0as–?ýan“int“(signed“or“unsigned),“but“not“necessarily“as“large“as“a“long.ŽŸ8äïhtml:ï html:¦‘0There–?ýis“also“an“option“to“override“the“default“member“type“so“that“it“can“be“largerŽ¡‘0than–?ýa“id“pointer.‘ úUse“of“this“option,“however,“changes“the“way“member“values“mustŽ¡‘0be–?ýpassed“to“or“from“a“collection.‘ úMore“information“is“given“with“the“MemberTypeŽ¡‘0option‘?ýbelow.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŸÐ7ÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸOi‘0Â@deftype–ffCollection“ŽŸˆ‰¿(..‘ úSetInitialValue–?ýand“Copy“behavior“is“currently“implemented“for“Array“and“List,“but“notŽ¡for–?ýSet“or“Map.)Ž¦ïhtml:ï html:Ÿ O¥‘0The–?ýCollection“type“inherits“standard“messages“from“the“defobj“library“for“creatingŽ¡‘0and–?ýcustomizing“objects.‘ úThese“messages“are“defined“as“part“of“the“defobj“CreateŽ¡‘0supertype.‘ úThe–?ýonly“collection“types“which“are“directly“creatable,“however,“are“thoseŽ¡‘0directly–?ýtagged“as“such“(with“the“CREATABLE“type“tag).Ž¦ïhtml:ï html:Ÿ O¥‘0In–?ýaddition“to“the“standard“create“messages“inherited“from“the“defobj“Create“supertype,Ž¡‘0Collection–?ýinherits“the“SetIntialValue,“Copy,“and“Drop“types“(also“from“defobj).‘ úCopyingŽ¡‘0or–?ýdropping“a“collection“has“no“effect“on“objects“which“might“have“be“contained“inŽ¡‘0a–?ýcollection“as“members;“only“the“references“to“objects“contained“in“the“collectionŽ¡‘0are–?ýcopied“or“freed.Ž¦ïhtml:ï html:Ÿ O¥‘0SetInitialValue–?ýdefines“special“create“messages“to“load“the“initial“members“of“a“newlyŽ¡‘0created–?ýcollection“from“an“existing“collection,“and“optionally“to“make“the“membersŽ¡‘0of–?ýa“collection“read-only“after“this“initialization.‘ úIf“the“members“of“a“collectionŽ¡‘0are–?ýread-only,“all“collection“messages“which“add,“replace,“or“remove“members“willŽ¡‘0raise–?ýan“InvalidOperation“error.‘ úEven“if“a“collection“was“not“initially“created“withŽ¡‘0ReadOnly–?ýstatus,“this“status“may“also“be“set“later.‘ úIf“a“collection“is“created“withŽ¡‘0the–?ýReadOnly“restriction“set,“however,“this“restriction“cannot“later“be“unset.Ž¦ïhtml:ï html:Ÿ O¥‘0A–?ýcollection“used“as“an“initial“value“need“not“have“the“same“type“as“a“collectionŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹g‡ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿being–?ýcreated.‘ úMembers“(and“keys,“too,“if“applicable)“are“added“to“the“new“collectionŽ¤‘/ºâin–?ýthe“same“order“as“defined“by“traversing“the“initial“value“collection“with“a“localŽ¡‘/ºâtemporary–?ýindex.‘ úCreate-time“options“are“also“applied“as“noted“under“SetInitialValue.Ž¡‘/ºâSome–?ýcollection“subtypes“may“have“further“special“rules“for“initial“values;“if“so,Ž¡‘/ºâthese–?ýare“documented“with“the“subtype.ŽºâŸ8äïhtml:ï html:©X‹‘0[aCollection–?ýcopy:› úaZone]“is“equivalent“to“[[aCollection“getType]“create:˜aZoneŽ¡‘0setInitialValue:‘ úaCollection].ŽŸÕSïhtml:ï html:Ÿ*‘0„¤ŽŽŸffïhtml:ï html:ŸÙÅCr½«eate-time‘™™optionsŽŸ‘ýïhtml:ï html:Ÿ £I‘0ÂCREATINGŽ¤ ‘o‘0-–ff(void)“setMemberType:“aDataType;Ž¡‘0-–ff(void)“setIndexSafety:“indexSafety;Ž¡‘0-–ff(void)“setIndexUpdateHandler:“(handler_t)handler“:“(void“*)arg;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setReplaceOnly:“(BOOL)replaceOnly;Ž¡‘0USINGŽ¡‘0-‘ffgetMemberType;Ž¡‘0-‘ffgetIndexSafety;Ž¡‘0-–ff(handler_t)“getIndexUpdateHandler:“(void“*)arg;Ž¡‘0-–ff(BOOL)“getReplaceOnly;ŽŸ bÌïhtml:ï html:Ÿ• ‘0ÊMemberT‘ÿ¬ypeŽŸÄ¢¿(..‘ úThis–?ýoption“is“not“currently“implemented“for“any“collection“types.)ŽŸ lïhtml:ï html:¦‘0The–?ýMemberType“option“may“be“used“to“declare“the“type“of“member“which“a“collectionŽ¤‘0contains.‘ úIts–?ývalue“must“be“an“objec“having“one“of“the“ValueType“types“defined“inŽ¡‘0defobj.‘ ú(..Currently–?ýno“ValueType“objects“are“implemented,“so“MemberType“is“not“supported.)ŽŸ8äïhtml:ï html:¦‘0The–?ýmember“type“defaults“to“the“Symbol“value“Unknown.‘ úSpecifying“a“member“type“hasŽ¡‘0no–?ýeffect“on“the“collection“if“the“storage“size“of“the“data“type“is“no“larger“thanŽ¡‘0a–?ýpointer“of“id“type.‘ úThe“member“type,“however,“may“be“helpful“as“documentation,Ž¡‘0and–?ýmembers“can“be“checked“for“conformance“to“the“type“as“part“of“debug“options.‘ úIfŽ¡‘0the–?ýdata“type“has“a“size“greater“than“id,“the“collection“automatically“allocates“andŽ¡‘0frees–?ýspace“for“the“member“value“whenever“member“values“are“added“or“removed.‘ úForŽ¡‘0such–?ýa“collection,“all“member“values“must“be“passed“to“the“collection“not“as“the“valueŽ¡‘0itself,–?ýbut“as“a“pointer“to“the“value“(cast“to“id“as“necessary).‘ úIf“a“new“memberŽ¡‘0is–?ýbeing“added,“the“value“will“be“copied“to“a“new“member“location“contained“withinŽ¡‘0the–?ýcollection.‘ úMember“values“returned“by“the“collection“will“be“returned“as“pointersŽ¡‘0to–?ýthis“internal“value,“not“as“the“value“itself.‘ úIn“the“case“of“member“values“removedŽ¡‘0from–?ýthe“collection,“a“nil“pointer“is“returned.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹h@ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÊIndexSafetyŽŸ ¬ºâ¿(..‘ úThis–?ýoption“is“not“currently“implemented“for“any“collection“types.)ŽºâŸ lïhtml:ï html:¤•‘0The–?ýIndexSafety“option“has“one“of“the“following“values:Ž©8äïhtml:ï html:Ÿïhtml:ï html:¡‘0Âid–ff‘ ÌÌUnsafe,“UnsafeAtMember,“SafeAlways;ŽŸ Öy¿If–?ýnot“specified,“the“default“value“depends“on“the“specific“collection“subtype.‘ úIn“typicalŽ¤cases,–?ýthe“default“value“is“Unsafe.‘ úA“non-default“value“is“required“for“indexes“to“have“aŽ¡guarantee–?ýof“safety“when“independent“modifications“to“the“underlying“collection“are“also“performed.Ž¦ïhtml:ï html:Ÿ•‘0Without–?ýa“guarantee“of“index“safety,“the“effect“of“any“operation“which“modifies“theŽ¡‘0underlying–?ýcollection“(adding,“removing,“or“replacing“members)“could“be“to“disruptŽ¡‘0the–?ýposition“assumed“by“any“existing“index.‘ úThe“effect“of“such“disruption“is,“inŽ¡‘0general,–?ýcompletely“unpredictable:‘ úit“could“be“an“immediate“crash,“a“wrong“sequenceŽ¡‘0of–?ýmembers,“or“other“difficult-to-debug“conditions.‘ úTo“avoid“such“unpredictability,Ž¡‘0several–?ýmeans“for“assuring“the“safety“of“indexes“under“independent“collection“updateŽ¡‘0are‘?ýprovided.Ž¦ïhtml:ï html:Ÿ•‘0The–?ýsimplest“way“to“guarantee“index“safety“is“to“set“the“IndexSafety“option“to“theŽ¡‘0value–?ýSafeAlways“when“a“collection“is“created.‘ úWith“the“value“of“SafeAlways,“anyŽ¡‘0active–?ýindex“on“the“collection“will“be“updated“automatically“to“reflect“any“changeŽ¡‘0to–?ýthe“underlying“collection“whenever“such“a“change“occurs.‘ úThis“automatic“updateŽ¡‘0continues–?ýto“occur“throughout“the“lifetime“of“any“index“on“the“collection;“it“ceasesŽ¡‘0to–?ýoccur“only“after“an“index“is“dropped.‘ úThis“is“the“easiest“option“to“use,“but“consumesŽ¡‘0extra–?ýresources“to“accomplish“(both“time“and“space“within“the“collection),“so“is“mostŽ¡‘0suitable–?ýwhen“the“extra“resource“usage“deesn't“matter“or“there's“no“better“way.Ž¦ïhtml:ï html:Ÿ•‘0With–?ýan“IndexSafety“value“of“SafeAlways,“there“is“also“an“additional“option“to“declareŽ¡‘0an–?ýexternal“index“update“handler.‘ úThe“handler“is“specified“using“the“setIndexUpdateHandler::Ž¡‘0message.‘ úIf–?ýan“IndexUpdateHandler“is“specified,“the“value“for“IndexSafety“is“alsoŽ¡‘0automatically–?ýset“to“SafeAlways.Ž¦ïhtml:ï html:Ÿ•‘0The–?ýfirst“argument“of“setIndexUpdateHandler::‘ úspecifies“a“function“which“is“calledŽ¡‘0whenever–?ýa“modification“to“the“underlying“collection“occurs“which“could“require“anŽ¡‘0update–?ýto“existing“indexes.‘ úThe“second“argument“establishes“a“pointer“value“whichŽ¡‘0the–?ýhandler“function“may“use“to“identify“the“indexes“which“need“to“be“updated,“orŽ¡‘0any–?ýother“information“needed“for“the“update.Ž¦ïhtml:ï html:Ÿ•‘0(..‘ úExact–?ýcall“conventions“for“the“IndexUpdateHandler“are“still“being“established,Ž¡‘0but–?ýthe“activity“library“will“soon“be“converted“to“use“this“technique,“so“the“conventionsŽ¡‘0will–?ýbe“resolved“during“that“conversion.)Ž¦ïhtml:ï html:Ÿ•‘0Besides–?ýthe“extreme“values“of“Unsafe“and“SafeAlways,“another“valid“value“for“IndexSafetyŽ¡‘0is–?ýUnsafeAtMember.‘ úThis“value“indicates“that“the“only“modification“of“the“collectionŽ¡‘0which–?ýcould“disrupt“existing“indexes“is“to“remove“the“member“contained“at“the“currentŽ¡‘0index–?ýposition,“or“to“change“the“member“on“either“side“of“an“index“positioned“betweenŽ¡‘0members.‘ úFor–?ýsome“collection“subtypes,“this“level“of“safety“is“automatically“assured,Ž¡‘0and–?ýfor“others“it“can“be“requested“with“less“overall“resource“impact“than“SafeAlways.Ž¦ïhtml:ï html:¡ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹i*, “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÊReplaceOnlyŽŸÓ ºâ¿(..‘ úThis–?ýoption“is“not“currently“implemented“for“any“collection“types.)ŽºâŸ lïhtml:ï html:Ÿ g‰‘0This–?ýboolean-valued“option“restricts“valid“usage“of“a“collection“by“excluding“allŽ¤‘0operations–?ýwhich“add“or“remove“members.‘ úFor“some“collection“subtypes,“a“replace-onlyŽ¡‘0restriction–?ýcan“obtain“many“of“the“same“performance“advantages“as“a“read-only“collection,Ž¡‘0but–?ýwithout“disabling“replace“operations“as“well.‘ úJust“like“the“ReadOnly“option,Ž¡‘0the–?ýReplaceOnly“option“may“be“reset“after“a“collection“is“created,“provided“it“wasŽ¡‘0not–?ýoriginally“set“to“true.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŸèÅCollection‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸgM‘0Â-–ff(int)“getCount;ŽŸ m¿getCount–?ýreturns“the“integer“number“of“members“currently“contained“in“the“collection.‘ úAllŽ¡collections–?ýmaintain“their“count“internally“so“that“no“traversal“of“collection“members“is“requiredŽ¡simply–?ýto“return“this“value.Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ g‰‘0Â-–ffatOffset:“(int)offset;Ž¤ m‘0-–ffatOffset:“(int)offset“put:“anObject;Ž¡¡‘0-‘ffgetFirst;Ž¡‘0-‘ffgetLast;Ž¡¿An–?ýoffset“is“an“integer“value“that“gives“relative“position“of“a“member“in“the“enumeration“sequenceŽ¤of–?ýa“collection.‘ úOffsets“start“the“count“of“the“first“member“at“zero,“just“like“C“array“indexing.Ž¦ïhtml:ï html:Ÿ g‰‘0Offsets–?ýprovide“an“alternate“means“to“access“the“members“of“a“collection,“withoutŽ¡‘0creating–?ýa“separate“index“object.‘ úSome“collection“subtypes“(such“as“Array)“supportŽ¡‘0fast,–?ýdirect“access“by“integer“member“offset,“while“others“support“member“offsetsŽ¡‘0only–?ýas“a“shorthand“for“sequential“access“through“every“preceding“member.‘ úAccessŽ¡‘0by–?ýoffsets“is“supported“on“all“collections“regardless“of“whether“its“speed“on“a“particularŽ¡‘0collection‘?ýtype.Ž¦ïhtml:ï html:Ÿ g‰‘0The–?ýatOffset:› úmessage“returns“the“member“at“a“particular“member“offset.˜The“atOffset:Ž¡‘0put:‘ úmessage–?ýreplaces“the“member“at“a“particular“offset“with“a“new“value,“and“returnsŽ¡‘0the–?ýprevious“member“value“at“this“offset.‘ úBoth“these“messages“raise“the“error“OffsetOutOfRangeŽ¡‘0if–?ýthe“offset“is“less“than“zero“or“greater“than“or“equal“to“the“count“of“members“inŽ¡‘0the‘?ýcollection.ŽŸïhtml:ï html:Ÿ m‘0The–?ýgetFirst“message“is“equivalent“to“[aCollection“atOffset:‘ ú0],“and“the“getLastŽ¡‘0message–?ýis“equivalent“to“[aCollection“atOffset:‘ ú[aCollection“getCount]“-“1].Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ g‰‘0Â-–ff(BOOL)“contains:“aMember;Ž¤ m‘0-–ffremove:“aMember;Ž¡‘0-–ff(void)“removeAll;Ž¡¿The–?ýcontains:‘ úmessage“returns“true“if“the“collection“contains“any“member“value“which“matchesŽŸthe–?ývalue“passed“as“its“argument.‘ úDepending“on“the“collection“subtype,“this“may“require“traversingŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹j9ÿ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿sequentially–?ýthrough“all“members“of“the“collection“until“a“matching“member“is“found.‘ úFor“otherŽ¤ºâsubtypes,–?ýsome“form“of“direct“indexing“from“the“member“value“may“be“supported.‘ úThe“messageŽ¡ºâis–?ýsupported“regardless“of“its“speed.Žºâ©8äïhtml:ï html:Ÿ Ç‘0The–?ýremove:‘ úmessage“removes“the“first“member“in“the“collection“with“a“value“matchingŽ¡‘0the–?ývalue“passed“as“its“argument.‘ úIf“there“is“no“such“member,“a“nil“value“is“returned.Ž¡‘0As–?ýwith“the“contains:‘ úmessage,“the“speed“of“this“operation“may“vary“from“very“lowŽ¡‘0to–?ýlinear“in“the“number“of“members,“depending“on“the“collection“subtype.Ž¦ïhtml:ï html:Ÿ Ç‘0The–?ýremoveAll“message“removes“all“existing“members“of“a“collection“and“sets“its“memberŽ¡‘0count–?ýto“zero.‘ úThe“collection“then“remains“valid“for“further“members“to“be“added.Ž¡‘0This–?ýmessage“has“no“effect“on“the“objects“which“might“be“referenced“by“any“removedŽ¡‘0member–?ývalues.‘ úIf“resources“consumed“by“these“objects“also“need“to“be“released,“suchŽ¡‘0release–?ýoperations“(such“as“drop“messages)“can“be“performed“prior“to“removing“theŽ¡‘0member‘?ývalues.Ž¤ïhtml:ï html:¡ïhtml:ï html:¤‘0Â-–ffbegin:“aZone;Ž¡¿The–?ýbegin:‘ úmessage“is“the“standard“method“for“creating“a“new“index“for“traversing“the“elementsŽ¡of–?ýa“collection.‘ úAll“further“information“about“indexes“is“documented“under“the“Index“type.Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ Ç‘0Â-–ff(void)“forEach:“(SEL)aSelector;Ž¡‘0-–ff(void)“forEach:“(SEL)aSelector“:“arg1;Ž¡‘0-–ff(void)“forEach:“(SEL)aSelector“:“arg1“:“arg2;Ž¡‘0-–ff(void)“forEach:“(SEL)aSelector“:“arg1“:“arg2“:“arg3;Ž¡¿The–?ýforEach“messages“supply“a“convenient“shorthand“for“repeatedly“performing“the“same“messageŽ¡on–?ýall“objects“contained“as“members“in“a“collection.‘ úThe“message“to“be“sent“is“identifiedŽ¡by–?ýthe“argument“aSelector.‘ úThis“selector“must“define“the“same“number“of“arguments“as“containedŽ¡in–?ýany“remaining“argument“slots“of“the“forEach“message.‘ úThe“argument“types“of“the“messageŽ¡to–?ýbe“sent“must“be“either“the“id“type,“or“some“other“type“that“will“fit“in“the“same“numberŽ¡of–?ýbits“as“the“id“type.‘ úBy“global“portability“assumptions,“the“argument“type“could“be“as“largeŽ¡as–?ýan“int“(signed“or“unsigned),“but“not“necessarily“as“large“as“a“long.‘ úTo“use“the“message,Ž¡any–?ýnon-id“value“must“be“cast“to“the“id“type“as“part“of“the“call“expression.Ž¦ïhtml:ï html:Ÿ Ç‘0The–?ýforEach:‘ úmessages“are“implemented“by“a“simple“loop“through“all“members“of“a“collection,Ž¡‘0using–?ýan“internal,“temporary“index.‘ úIf“any“operation“more“complex“than“a“simple“messageŽ¡‘0send–?ýis“required,“this“operation“should“just“be“coded“directly“using“a“loop“that“traversesŽ¡‘0its–?ýown“index.ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹kFØ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ†ÅIndex–™™{“r•½«efer“ence–™™into“an“enumeration“sequence“f£×or“a“collectionŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸËÏÀSynopsisŽŸ âcïhtml:ï html:Ÿ‹7‘0Â//Ž¤e‘0//–ffIndex“--“reference“into“an“enumeration“sequence“for“a“collectionŽ¡‘0//Ž¡‘0@deftype–ffIndex“-“getCollection;Ž¡¡‘0-‘ffnext;Ž¡‘0-‘ffprev;Ž¡‘0-–fffindNext:“anObject;Ž¡‘0-–fffindPrev:“anObject;Ž¡¡‘0-‘ffget;Ž¡‘0-–ffput:“anObject;Ž¡‘0-‘ffremove;Ž¡¡‘0-‘ffgetLoc;Ž¡‘0-–ff(void)“setLoc:“locSymbol;Ž¡‘0-–ff(int)“getOffset;Ž¡‘0-–ffsetOffset:“(int)offset;Ž¡¡‘0-–ff(int)“compare:“anIndex;Ž¡‘0@endŽŸdwïhtml:ï html:Ÿ¯ÀDescriptionŽŸmš¿An–?ýindex“is“a“reference“into“an“enumeration“sequence“of“a“collection.‘ úSuch“an“enumerationŽ¤sequence–?ýcontains“all“members“of“the“collection“in“some“order.‘ úThis“order“will“always“be“consistentŽ¡with–?ýordering“of“members“in“the“collection,“assuming“there“is“such“an“ordering.‘ úOtherwise,Ž¡the–?ýsequence“will“still“contain“all“members“in“some“order“that“remains“fixed“provided“thatŽ¡new–?ýmembers“are“not“added“or“removed“from“the“collection.ŽŸ ^5ïhtml:ï html:Ÿe‘0An–?ýindex“is“created“by“a“begin:› úor“createIndex:˜message“against“a“collection.˜EachŽ¡‘0major–?ýcollection“type“has“its“own“corresponding“index“type,“which“supports“specializedŽ¡‘0types–?ýof“processing“against“the“valid“contents“of“that“kind“of“collection.‘ úOnce“created,Ž¡‘0an–?ýindex“is“a“separate“object“from“the“collection“itself,“but“it“remains“valid“onlyŽ¡‘0so–?ýlong“as“the“collection“itself“still“exists.‘ úMultiple“indexes“may“exist“at“theŽ¡‘0same–?ýtime“against“the“same“collection,“and“each“index“maintains“its“own“position“withinŽ¡‘0an–?ýenumeration“sequence“for“the“collection.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹lTE “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0¿Many–?ýindexes“provde“the“ability“modify“the“collection“they“refer“to,“in“addition“toŽ¤‘0simply–?ýtraversing“members.‘ úAn“index“often“provides“the“complete“means“for“maintainingŽ¡‘0the–?ýcontents“of“a“collection,“more“than“could“otherwise“be“performed“on“the“collectionŽ¡‘0itself.‘ úThe–?ýposition“or“other“status“of“the“index“is“automatically“updated“to“reflectŽ¡‘0any–?ýchanges“made“through“the“index“itself.Ž©8äïhtml:ï html:Ÿ $ ‘0If–?ýchanges“to“a“collection“are“made“while“other“indexes“exist,“those“other“indexesŽ¡‘0could–?ýbe“affected“in“potentially“catastrophic“ways.‘ úEach“collection“type“documentsŽ¡‘0which–?ýkinds“of“changes“can“be“made“without“affecting“or“invalidating“existing“indexes.Ž¡‘0The–?ýIndexSafety“option“of“Collection“provides“additional“ways“to“protect“indexes“againstŽ¡‘0possible–?ýeffects“of“independent“updates.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ¤²ÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ#ä‘0Â@deftype–ffIndex“ŽŸ]¿Each–?ýindex“is“a“stand-alone“object“allocated“within“a“zone“passed“as“an“argument“in“the“messageŽ¡that–?ýcreated“it.› úThis“zone“need“not“match“the“zone“of“a“collection.˜It“is“common“for“indexŽ¡lifetimes–?ýto“be“shorter“than“their“collection.‘ úFor“example,“indexes“can“be“created“in“a“temporaryŽ¡scratch–?ýzone“for“use“only“within“a“local“loop.Ž¦ïhtml:ï html:Ÿ $ ‘0Because–?ýmessages“to“a“collection“are“the“only“valid“way“to“create“an“index,“createŽ¡‘0messages–?ýand“create-time“options“are“not“used“with“index“types.‘ úAll“valid“processingŽ¡‘0on–?ýan“index“is“determined“by“characteristics“of“the“collection“from“which“it“is“created.Ž¡‘0Index–?ýtypes“are“typically“named“after“the“type“of“collection“they“are“created“from,Ž¡‘0and–?ýserve“principally“to“define“the“specific“messages“valid“for“an“index“on“that“typeŽ¡‘0of‘?ýcollection.ŽŸïhtml:ï html:Ÿ]‘0Index–?ýobjects“support“the“universal“messages“of“the“top-level“DefinedObject“supertype,Ž¡‘0along–?ýwith“the“standard“drop:› úand“getZone“messages.˜Even“though“they“cannot“be“createdŽ¡‘0except–?ýfrom“a“collection,“new“index“objects“can“be“created“from“an“existing“indexŽ¡‘0using–?ýthe“standard“copy:– úmessage.“Each–?ýcopy“refers“to“the“same“collection“as“theŽ¡‘0initial–?ýindex,“and“starts“at“the“same“position“in“its“enumeration“sequence.‘ úIn“allŽ¡‘0other–?ýrespects,“however,“the“new“copy“is“an“independent“index“that“maintains“its“ownŽ¡‘0position–?ýunder“any“further“processing.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ¤²ÅIndex‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ#ä‘0Â-‘ffgetCollection;ŽŸ]¿getCollection–?ýreturns“the“collection“referred“to“by“an“index.‘ úThis“collection“never“changesŽ¡during–?ýthe“lifetime“of“the“index.Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ $ ‘0Â-‘ffnext;Ž¤]‘0-‘ffprev;Ž¡¿The–?ýnext“and“prev“messages“are“the“basic“means“to“traverse“through“the“members“of“a“collection.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹m\® “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿The–?ýnext“message“positions“the“index“to“the“next“valid“member“after“its“current“position,“orŽ¤ºâto–?ýa“special“position“after“the“end“of“all“valid“members.‘ úThe“prev“message“works“similarly,Ž¡ºâbut–?ýpositions“to“a“valid“member“preceding“the“current“position,“or“to“a“special“position“precedingŽ¡ºâall–?ývalid“members.‘ úIn“addition“to“repositioning“the“index,“both“messages“return“the“new“memberŽ¡ºâvalue–?ýto“which“they“are“positioned,“or“nil“if“there“is“no“such“member.Žºâ©8äïhtml:ï html:Ÿ ÕU‘0Following–?ýis“a“standard“form“of“loop“which“may“be“used“to“enumerate“the“members“ofŽ¡‘0a–?ýcollection“using“an“index:Ž¦ïhtml:ï html:Ÿ ÕU‘0Âindex–ff=“[aCollection“begin:“aZone];Ž¤9‘:ÌÌwhile–ff(“(member“=“[index“next])“)“ÇfŽ¡‘E™˜Â//–ffdo“something“with“member“...Ž¡‘:ÌÌÇgŽ¡¿When–?ýfirst“created,“the“current“position“of“an“index“is“always“set“to“the“special“positionŽ¤preceding–?ýall“valid“members.‘ úFrom“this“initial“position,“this“loop“accesses“each“succeedingŽ¡member–?ýin“turn.‘ úIt“assigns“each“member“value“to“a“local“variable“("member"“in“this“example)Ž¡until–?ýa“nil“value“is“returned.Ž¤ïhtml:ï html:¡ïhtml:ï html:¤9‘0Â-–fffindNext:“anObject;Ž¡‘0-–fffindPrev:“anObject;Ž¡¿findNext:– úand›?ýfindPrev:“repeatedly˜perform˜next˜or˜prev˜until˜the˜member˜value˜of˜the˜indexŽ¤matches–?ýtheir“argument.‘ únil“is“returned“if“the“index“reaches“the“end“of“valid“members“withoutŽ¡matching–?ýthe“argument.‘ úThey“are“only“convenience“shorthands“for“loops“which“could“otherwiseŽ¡be–?ýprogrammed“using“next“or“prev.Ž¦ïhtml:ï html:©ïhtml:ï html:Ÿ ÕU‘0Â-‘ffget;Ž¤9‘0-–ffput:“anObject;Ž¡‘0-‘ffremove;Ž¡¿get–?ýreturns“the“member“value“at“which“the“index“is“currently“positioned,“or“nil“if“the“indexŽ¤is–?ýnot“positioned“at“a“member“The“put:‘ úmessage“replaces“the“member“value“at“the“current“indexŽ¡position–?ýwith“its“argument.‘ úNeither“of“these“messages“changes“the“current“position“of“theŽ¡index.Ž¦ïhtml:ï html:Ÿ9‘0The–?ýget“message“provides“an“alternate“way“to“obtain“the“current“member“value“in“aŽ¡‘0loop–?ýthat“traverses“a“collection;“its“return“value“is“the“same“as“next“or“prev“wouldŽ¡‘0return–?ýwhen“first“positioning“to“a“new“member.ŽŸ8äïhtml:ï html:Ÿ ÕU‘0The–?ýremove“message“removes“the“member“at“the“current“location“of“an“index,“and“returnsŽ¡‘0the–?ýmember“value“removed.‘ úThe“index“position“is“set“to“a“special“position“betweenŽ¡‘0the–?ýmembers“which“previously“preceded“and“followed“the“removed“member.‘ úIf“there“isŽ¡‘0no–?ýpreceding“or“following“member,“the“index“is“set“to“the“special“location“beforeŽ¡‘0the–?ýstart“or“after“the“end“of“all“members.‘ úAfter“a“current“member“is“removed,“thereŽ¡‘0is–?ýno“member“at“the“current“index“location,“but“a“subsequent“next“or“prev“messageŽ¡‘0will–?ýcontinue“with“the“same“member“that“would“have“been“accessed“had“the“current“memberŽ¡‘0not–?ýbeen“removed.Ž¦ïhtml:ï html:Ÿ9‘0Both–?ýput:‘ úand“remove“raise“the“InvalidIndexLoc“error“if“the“index“is“not“positionedŽ¡‘0at–?ýa“current“member.Ž¦ïhtml:ï html:¦ïhtml:ï html:¤9‘0Â-‘ffgetLoc;Ž¡‘0-–ff(void)“setLoc:“locSymbol;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹nj$ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿The–?ýgetLoc“message“returns“a“symbol“constant“which“indicates“the“type“of“location“at“whichŽ¤ºâan–?ýindex“is“currently“positioned.‘ úThis“index“location“symbol“has“one“of“the“following“values:Žºâ©8äïhtml:ï html:Ÿ Ç‘0Âextern–ffid“‘ ÌÌStart,“End,“Between,“Member;ŽŸ ¿The–?ýStart“symbol“indicates“the“special“position“preceding“all“members“in“the“enumeration“sequenceŽ¡for–?ýthe“collection.‘ úThis“is“the“location“at“which“an“index“is“positioned“when“it“is“firstŽ¡created.‘ úThe–?ýEnd“symbol“indicates“the“special“position“following“all“members“in“the“collection.Ž¡This–?ýis“the“location“at“which“an“index“is“positioned“just“after“a“next“message“has“returnedŽ¡nil,–?ýas“a“result“of“moving“beyond“the“last“member.‘ úThe“Between“symbol“indicates“the“specialŽ¡position–?ýbetween“two“other“members,“at“which“an“index“is“positioned“after“a“current“member,Ž¡between–?ýtwo“other“members,“is“removed.‘ úThe“Member“symbol“indicates“that“the“index“is“positionedŽ¡at–?ýsome“current“member“in“the“enumeration“sequence“of“a“collection.Ž¦ïhtml:ï html:Ÿ Ç‘0The–?ýgetLoc“message“is“needed“to“traverse“a“collection“which“could“contain“nil“valuesŽ¡‘0for–?ýits“members.‘ úWithout“getLoc,“there“would“be“no“way“to“distinguish“a“nil“valueŽ¡‘0returned–?ýby“next“as“either“a“valid“member“value“or“the“special“value“returned“at“theŽ¡‘0end–?ýof“members.‘ úWith“getLoc,“a“loop“that“traverses“a“collection“can“test“specificallyŽ¡‘0for–?ýthe“end“(or“start)“of“members.‘ úFollowing“is“a“simple“loop“which“illustrates“suchŽ¡‘0usage:› úindex–?ý=“[aCollection“begin:˜aZone];“do“ó !",š cmsy10¸f“¿member“=“[index“next];“//“do“somethingŽ¡‘0with–?ýmember“...› ú¸g“¿while“(“[index“getLoc]“==“Member“);“The“setLoc:˜message“may“beŽ¡‘0used–?ýto“reset“the“current“location“of“an“index“to“either“Start“or“End.‘ úIt“may“beŽ¡‘0used–?ýto“reprocess“a“collection“using“an“existing“index“after“some“other“location“hasŽ¡‘0already–?ýbeen“reached.‘ úIt“may“also“be“used“to“position“an“index“at“the“end“of“allŽ¡‘0members–?ýprior“to“traversing“members“in“reverse“order“using“prev.Ž¦ïhtml:ï html:Ÿ Ç‘0Besides–?ýStart“and“End,“setLoc:‘ úaccepts“the“special“argument“values“of“BetweenAfterŽ¡‘0and–?ýBetweenBefore,“which“are“also“defined“symbols.‘ úThese“argument“values“are“onlyŽ¡‘0valid–?ýif“the“index“is“positioned“at“a“current“member.‘ úThey“reposition“the“index“toŽ¡‘0the–?ýspecial“location“between“the“current“member“and“its“immediately“following“or“precedingŽ¡‘0member.Ž¤ïhtml:ï html:¡ïhtml:ï html:¤ ‘0Â-–ff(int)“getOffset;Ž¡‘0-–ffsetOffset:“(int)offset;Ž¡¿Provided–?ýthere“is“no“major“computational“cost,“an“index“also“maintains“the“integer“offset“ofŽ¤its–?ýcurrent“member“within“the“enumeration“sequence“of“the“collection.‘ úThese“integer“offsetŽ¡values–?ýhave“the“same“definition“as“in“the“atOffset:› úmessages“of“Collection.˜The“getOffsetŽ¡message–?ýreturns“this“current“offset“value.‘ úIf“the“index“is“current“positioned“at“the“StartŽ¡or–?ýEnd“location,“getOffset“returns“-1.‘ úIf“the“index“is“positioned“at“a“Between“location,“getOffsetŽ¡returns–?ýthe“offset“of“the“immediately“preceding“member.‘ úIf“the“offset“is“not“currently“availableŽ¡from–?ýthe“index,“getOffset“returns“the“special“value“UnknownOffset.‘ úThis“value“is“defined“byŽ¡a–?ýmacro“as“the“maximally“negative“value“of“a“32-bit,“2's-complement“integer.Ž¦ïhtml:ï html:Ÿ Ç‘0An–?ýoffset“is“always“available“from“an“index“if“its“current“position“has“been“reachedŽ¡‘0by–?ýrepeated“operations“from“an“initial“Start“or“End“position,“and“there“has“been“noŽ¡‘0other–?ýmodification“to“the“underlying“collection.‘ úSome“forms“of“direct“member“accessŽ¡‘0operations–?ýsupported“by“some“index“types,“however,“may“result“in“an“integer“offsetŽ¡‘0not–?ýbeing“available.‘ úThese“restrictions“are“noted“with“the“individual“index“type.Ž¦ïhtml:ï html:Ÿ Ç‘0Using–?ýthe“setOffset:‘ úmessage,“an“index“may“be“positioned“directly“to“a“member“usingŽ¡‘0the–?ýoffset“of“the“member“within“its“enumeration“sequence.‘ úThe“speed“of“this“operationŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ox4 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿depends–?ýon“the“specific“type“of“the“collection,“just“as“noted“for“the“atOffset:‘ úmessageŽ¤‘/ºâon–?ýCollection.‘ úIn“the“worst“case,“this“operation“is“linear“in“the“magnitude“of“theŽ¡‘/ºâoffset.Žºâ¤ïhtml:ï html:¡ïhtml:ï html:¤‘0Â-–ff(int)“compare:“anIndex;Ž¡¿The–?ýcompare:‘ úmessage“compares“the“current“location“of“one“index“with“the“current“locationŽ¡of–?ýanother“index“passed“as“its“argument.‘ úIf“the“two“indexes“have“the“same“location,“compare:Ž¡returns–?ýzero.› úOtherwise,“compare:˜returns“+1“or“-1“according“to“whether“the“argument“indexŽ¡precedes–?ýor“follows“the“receiver“index“in“the“enumeration“sequence“of“the“collection.‘ úIf“eitherŽ¡of–?ýthe“two“indexes“has“an“unknown“offset,“and“the“location“of“the“other“index“is“anything“otherŽ¡than–?ýStart“or“End“or“an“immediately“adjacent“member,“compare:‘ úreturns“the“UnknownOffset“integerŽ¡value.ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹p‰¨ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸƒçÅArray–™™{“collection“supporting“access“to“xed“gr½«oup“of“membersŽ©‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ=0ÀSynopsisŽŸ âcïhtml:ï html:Ÿü˜‘0Â//Ž¤€Æ‘0//–ffArray“--“collection“supporting“access“to“fixed“group“of“membersŽ¡‘0//Ž¡‘0@deftype–ffArray“CREATINGŽ¡‘0+–ffcreate:“aZone“setCount:“(int)count;Ž¡‘0+–ffcreate:“aZone“setMemberBlock:(id“*)members“setCount:(int)count;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setCount:“(int)count;Ž¡‘0-–ff(void)“setDefaultMember:“memberValue;Ž¡¡‘0-–ff(void)“setMemberBlock:“(id“*)members“setCount:“(int)count;Ž¡‘0USINGŽ¡‘0-‘ffgetDefaultMember;Ž¡‘0-–ff(id“*)“getMemberBlock;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ=0ÀDescriptionŽŸÞû¿An–?ýarray“is“a“collection“of“members“that“are“all“created“as“members“of“the“collection“at“theŽ¤same–?ýtime.‘ úExisting“member“values“may“be“replaced“with“new“values,“but“the“members“themselvesŽ¡are–?ýfixed“at“constant“offsets“within“the“collection.‘ úThe“fixed“structure“of“an“array“permitsŽ¡very–?ýfast“access“to“members“by“integer“offset“positions,“since“the“location“of“each“memberŽ¡may–?ýbe“directly“calculated.ŽŸ—ïhtml:ï html:© Gâ‘0The–?ýArray“type“is“one“of“the“simplest“collection“types“in“the“collections“library,Ž¡‘0and–?ýthe“closest“to“a“data“structure“directly“supported“in“C.“Unlike“C“arrays,“theŽ¡‘0group–?ýof“members“belonging“to“the“array“is“not“necessarily“fixed“for“the“lifetimeŽ¡‘0of–?ýthe“array,“but“may“be“dynamically“resized“to“contain“a“different“number“of“members.Ž¡‘0When–?ýan“array“is“dynamically“resized,“existing“member“values“are“preserved“as“muchŽ¡‘0as‘?ýpossible.ŽŸ8äïhtml:ï html:¦‘0The–?ýArray“type“adds“few“messages“to“the“generic“messages“inherited“from“Collection.Ž¡‘0This–?ýtype“is“provided“partly“so“that“a“fixed-structure“array“can“be“accessed“withŽ¡‘0the–?ýsame“uniform“set“of“basic“messages“as“any“other“kind“of“object“collection.‘ úItŽ¡‘0also–?ýhandles“all“required“memory“allocation“within“the“collection.‘ úAs“an“option,ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹qT “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿however,–?ýthe“Array“type“can“be“used“to“wrap“an“existing“C“array“for“external“accessŽ¤‘/ºâas–?ýan“object“collection.‘ úIt“can“also“provide“access“to“an“internal“C“array“for“directŽ¡‘/ºâmanipulation–?ýusing“C“expressions.‘ úThese“forms“of“low-level“access“support“hybridŽ¡‘/ºâmodes–?ýof“use“in“which“advantages“of“both“low-level“manipulation“and“external“objectŽ¡‘/ºâaccess–?ýcan“be“combined.ŽºâŸïhtml:ï html:Ÿ‘0„¤ŽŽŸffïhtml:ï html:Ÿk8ÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿêj‘0Â@deftype–ffArray“ŽŸ#Š¿The–?ýArray“type“is“directly“creatable,“and“supports“all“standard“messages“of“Collection“exceptŽ¡removal–?ýof“individual“members.‘ úThe“messages“based“on“an“integer“offset,“either“on“the“collectionŽ¡(atOffset:,–?ýatOffset:put:),“or“an“index“(setOffset:)› úall“execute“in“fast“constant“time.˜MembersŽ¡of–?ýan“array“are“fully“ordered“according“to“these“integer“offsets.‘ úSequential“access“to“membersŽ¡through–?ýits“members“is“also“fully“supported.‘ úThe“Array“type“disables“the“remove“message“inheritedŽ¡from–?ýCollection;“the“message“is“defined,“but“any“attempt“to“remove“a“member“will“raise“an“errorŽ¡that–?ýthe“operation“is“not“supported.Ž©8äïhtml:ï html:Ÿ ê¦‘0While–?ýthe“IndexSafety“option“of“an“Array“defaults“to“Unsafe,“indexes“are“inherentlyŽ¡‘0safe–?ýunder“all“operations“with“the“exception“of“resizing“an“array“or“resetting“itsŽ¡‘0member–?ýallocation.‘ ú(The“only“individual“member“operation“which“modifies“contentsŽ¡‘0of–?ýan“array“is“replacing“a“member“value,“and“this“does“not“affect“existing“indexes.)Ž¡‘0The–?ýUnsafeAtMember“value“of“IndexSafety“is“not“supported“since“individual“membersŽ¡‘0cannot–?ýbe“added“or“removed.‘ úA“value“of“SafeAlways“makes“existing“indexes“safe“evenŽ¡‘0under–?ýresizing“or“reallocation.‘ úIf“an“existing“index“referred“to“a“member“locationŽ¡‘0that–?ýis“no“longer“contained“in“the“array,“the“index“location“is“reset“to“the“End“location.Ž¦ïhtml:ï html:¤ ê¦‘0The–?ýdefault“value“of“the“ReplaceOnly“option“is“true,“and“cannot“be“overridden.Ž¦ïhtml:ï html:¡‘0The–?ýtype“of“index“returned“by“begin:› úon“an“array“is“simply“Index.˜There“is“no“specialŽ¤‘0index–?ýtype“for“Array“because“there“are“no“additional“messages“beyond“those“alreadyŽ¡‘0defined–?ýby“Index.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿk8ÅCr½«eate-time‘™™optionsŽŸ‘ýïhtml:ï html:Ÿ 5d‘0ÂSETIINGŽ¤#Š‘0-–ff(void)“setCount:“(int)count;Ž¡‘0-–ff(void)“setDefaultMember:“memberValue;Ž¡¡‘0-–ff(void)“setMemberBlock:“(void“*)members“setCount:“(int)count;Ž¡‘0USINGŽ¡‘0-–ff(void)“setDefaultMember:“memberValue;Ž¡‘0-‘ffgetDefaultMember;Ž¡¡‘0-–ff(void)“setMemberBlock:“(void“*)members“setCount:“(int)count;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹r˜Ö “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ-–ff(void“*)“getMemberBlock;ŽŸBºâ¿All–?ýthe“Array“create-time“options“can“also“be“set“after“the“array“is“already“created,“subjectŽ¤ºâto–?ýrestrictions“noted“below.ŽºâŸïhtml:ï html:¡ïhtml:ï html:Ÿ¨ö‘0ÊCountŽ©uÃ¿The–?ýCount“option“sets“the“number“of“members“which“belong“to“the“collection.‘ úAny“non-negativeŽ¡value–?ýincluding“zero“is“valid.‘ úIf“the“array“already“exists,“the“any“existing“members“up“toŽ¡the–?ýnew“count“will“preserve“their“existing“values.‘ úIf“the“new“count“is“greater“than“the“existingŽ¡count,–?ýor“a“new“array“is“being“created,“all“members“will“be“assigned“an“initial“default“valueŽ¡of–?ýeither“nil,“or“a“value“previously“specified“for“DefaultMember.ŽŸ lïhtml:ï html:Ÿ ¬‘0The–?ýinherited“getCount“message“of“Collection“obtains“the“current“value“set“for“thisŽ¡‘0option.‘ úThere–?ýis“no“way“to“add“or“remove“members“of“an“array“except“using“the“setCount:Ž¡‘0message‘?ýdirectly.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:Ÿp‘0ÊDefaultMemberŽ¦¿When–?ýthis“option“is“set,“the“initial“value“of“all“new“members“will“be“set“to“the“member“valueŽ¡given–?ý(otherwise“the“default“is“nil).‘ úThis“option“gives“a“convenient“way“to“distinguish“membersŽ¡which–?ýhave“never“been“set“from“any“other“valid“member“value,“which“could“include“nil.‘ úThisŽ¡option–?ýmay“be“reset“after“array“creation“only“if“some“setting“for“the“option“was“given“at“createŽ¡time.‘ ú(The–?ýinitial,“explicitly“set“value“can“still“be“the“default“nil,“but“a“value“must“beŽ¡set–?ýexplicitly“for“the“option“to“be“resettable“later).‘ úThe“get“message“for“this“option“alwaysŽ¡retrieves–?ýthe“current“setting,“but“this“value“has“no“effect“except“when“the“count“of“an“arrayŽ¡is–?ýincreased,“so“that“new“members“need“to“be“initialized.ŽŸ–Àïhtml:ï html:¡ïhtml:ï html:Ÿ Ei‘0ÊMemberBlockŽ¦¿This–?ýoption“provides“a“means“to“wrap“an“existing“C“array“for“access“as“an“object“collection.Ž¡If–?ýthis“option“is“given,“dynamic“resizing“is“not“supported.‘ úThe“current“C“array“being“wrapped,Ž¡however,–?ýcan“be“replaced“by“giving“a“new“setting“for“MemberBlock“after“an“array“already“exists.Ž¡A–?ýnew“setting“can“be“given“only“if“some“setting“was“initially“given“at“create“time.ŽŸ lïhtml:ï html:© ¬‘0Even–?ýif“a“setting“was“not“given“for“MemberBlock“at“create“time,“the“get“message“forŽ¡‘0MemberBlock–?ýalways“returns“a“pointer“to“whatever“internal“memory“array“is“currentlyŽ¡‘0being–?ýused“by“the“array“object.‘ úIf“a“MemberBlock“setting“was“given,“the“pointer“returnedŽ¡‘0will–?ýbe“the“same“as“the“one“previously“given.‘ úIn“either“case,“the“pointer“returnedŽ¡‘0may–?ýbe“used“to“manipulate“member“values“in“any“way“desired“using“native“C“expressions.Ž¡‘0After–?ýan“array“has“been“created,“there“is“no“way“to“determine“whether“the“MemberBlockŽ¡‘0pointer–?ýwas“established“externally“or“by“internal“allocation.‘ úIf“the“pointer“wasŽ¡‘0established–?ýby“internal“allocation,“however,“the“external“program“must“make“no“attemptŽ¡‘0to–?ýfree“or“otherwise“reallocate“this“memory.ŽŸ8äïhtml:ï html:¦‘0A–?ýcount“must“always“be“supplied“with“an“external“member“allocation,“using“the“setCount:Ž¡‘0argument–?ýof“the“compound“message.‘ úIf“an“external“allocation“is“being“used,“the“onlyŽ¡‘0way–?ýto“reset“the“count“is“also“to“reset“MemberBlock;“any“attempt“to“use“the“setCount:Ž¡‘0message–?ýby“itself“will“raise“an“error.‘ úWhenever“an“external“member“allocation“isŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹s¥- “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿being–?ýused,“the“external“program“is“entirely“responsible“for“assuring“that“the“MemberBlockŽ¤‘/ºâvalue–?ýis“a“pointer“to“valid“allocated“memory“containing“at“least“the“number“of“memberŽ¡‘/ºâslots–?ýgiven“by“setCount:.Žºâ©8äïhtml:ï html:Ÿ Ç‘0With–?ýan“external“member“allocation,“the“array“itself“will“not“attempt“to“either“allocateŽ¡‘0this–?ýmemory“or“free“it“when“the“array“is“dropped.‘ úDropping“the“array“only“removesŽ¡‘0its–?ýreference“to“the“external“allocation.ŽŸïhtml:ï html:¡‘0The–?ýpointer“to“allocated“memory“is“given“as“a“pointer“to“id“type,“but“if“a“data“typeŽ¡‘0given–?ýas“MemberType“has“size“greater“than“id,“the“pointer“must“actually“point“to“anŽ¡‘0array–?ýof“slots“each“of“which“has“the“size“of“the“data“type.Ž¦ïhtml:ï html:Ÿ Ç‘0Since–?ýan“array“neither“allocates“nor“frees“an“external“member“allocation,“the“sameŽ¡‘0region–?ýof“allocated“memory“may“be“referenced“by“multiple“arrays,“including“overlappingŽ¡‘0member–?ýranges“each“defined“by“starting“location“and“count.‘ úThis“flexibility“enablesŽ¡‘0alternate–?ýsubrange“views“of“a“single,“contiguous“initial“allocation“by“means“of“separatelyŽ¡‘0created–?ýexternal“collections.ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸffïhtml:ï html:ŸG®ÅCr½«eate–™™combination“messagesŽŸ‘ýïhtml:ï html:Ÿ Ú‘0ÂCREATINGŽ¡‘0+–ffcreate:“aZone“setCount:“(int)count;Ž¡‘0+–ffcreate:“aZone“setMemberBlock:(id“*)members“setCount:(int)count;Ž¡¿In–?ýaddition“to“the“standard“inherited“create“messages,“the“Array“type“supports“two“forms“ofŽ¡combination–?ýmessages“which“both“create“the“array“and“set“its“initial“options.‘ úThese“are“providedŽ¡both–?ýfor“convenience“and“to“provide“the“fastest“possible“array“creation“for“simple“cases“inŽ¡which–?ýspeed“might“be“important.‘ úThe“two“cases“supported“are“creating“an“array“with“a“memberŽ¡count–?ýfor“its“internal“members“already“set,“and“creating“an“array“which“refers“to“an“externalŽ¡member–?ýallocation.‘ úIf“any“more“options“than“these“are“needed,“the“normal“method“of“settingŽ¡options–?ýbetween“createBegin:‘ úand“createEnd“messages“should“be“used“instead.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹t´ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸUBÅList,–™™ListIndex“{“collection“of“members“in“linear“sequenceŽ©‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ‹ÀSynopsisŽŸ âcïhtml:ï html:ŸÍó‘0Â//Ž¤R!‘0//–ffList“-“collection“of“members“in“linear“sequenceŽ¡‘0//Ž¡‘0@deftype–ffList“CREATINGŽ¡‘0-–ff(void)“setEndsOnly:“(BOOL)endsOnly;Ž¡‘0USINGŽ¡‘0-–ff(BOOL)“getEndsOnly;Ž¡¡‘0-–ff(void)“addFirst:“anObject;Ž¡‘0-–ff(void)“addLast:“anObject;Ž¡¡‘0-‘ffremoveFirst;Ž¡‘0-‘ffremoveLast;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffListIndex“--“index“with“insertion“capability“at“any“point“in“listŽ¡‘0//Ž¡‘0@deftype–ffListIndex“-“(void)“addAfter:“anObject;Ž¡‘0-–ff(void)“addBefore:“anObject;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ‹ÀDescriptionŽŸ°V¿A–?ýlist“is“a“collection“of“members“that“are“all“maintained“at“some“externally“assigned“positionŽ¤in–?ýa“linear“sequence“of“all“members.‘ úThe“sequence“is“established“by“the“position“at“whichŽ¡members–?ýare“added:‘ úmembers“can“be“added“at“the“start“of“list,“at“the“end,“or“at“any“pointŽ¡in–?ýthe“middle.ŽŸ ^5ïhtml:ï html:ŸR!‘0A–?ýlist“is“also“one“of“the“most“dynamic“of“basic“collections,“in“that“the“cost“of“addingŽ¡‘0and–?ýremoving“members“is“very“low.‘ úMembers“can“be“removed“from“any“position“just“asŽ¡‘0easily–?ýas“they“can“be“added.‘ úA“list“automatically“grows“and“shrinks“to“reflect“theŽ¡‘0number–?ýof“members“at“any“one“time,“and“there“is“no“fixed“capacity“which“limits“theŽ¡‘0size–?ýto“which“a“list“may“grow.ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹u¾â “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâŸffïhtml:ï html:ŸÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ™N‘0Â@deftype–ffList“ŽŸÒn¿The–?ýList“type“is“supports“all“messages“of“Collection.‘ úIf“created“with“default“options,“itŽ¤provides–?ýno“special“speedup“of“accesses“by“integer“offset.Ž©8äïhtml:ï html:Ÿ ™Š‘0Unless–?ýthe“EndsOnly“option“is“specified,“the“default“value“of“IndexSafety“is“UnsafeAtMember.Ž¡‘0This–?ýmeans“that“indexes“are“inherently“safe“under“all“operations“except“those“whichŽ¡‘0affect–?ýthe“member“at“an“index“or“immediately“adjacent“to“an“index“between“members.Ž¡‘0If–?ýthe“EndsOnly“option“is“specified,“the“default“value“of“IndexSafety“is“Unsafe.‘ úInŽ¡‘0this–?ýcase,“indexes“could“be“invalidated“by“any“operation“that“adds“or“removes“members.Ž¡‘0The–?ýSafeAlways“can“be“specified“for“any“case“to“get“a“guarantee“of“full“index“safety.Ž¦ïhtml:ï html:Ÿ ™Š‘0ListIndex–?ýis“a“special“index“type“just“for“list“collections.‘ úIt“provides“the“onlyŽ¡‘0method–?ýto“add“members“within“the“interior“of“a“list.ŽŸïhtml:ï html:©ffïhtml:ï html:ŸÅCr½«eate-time‘™™optionsŽŸ‘ýïhtml:ï html:Ÿ äH‘0ÂCREATINGŽ¤Òn‘0-–ff(void)“setEndsOnly:“(BOOL)endsOnly;Ž¡‘0USINGŽ¡‘0-–ff(BOOL)“getEndsOnly;ŽŸ bÌïhtml:ï html:Ÿ Ö‘0ÊEndsOnlyŽŸ¡¿(..› úThis–?ýoption“is“not“implemented“yet.)˜The“EndsOnly“option“restricts“a“list“so“that“membersŽ¤can–?ýbe“added“or“removed“only“at“either“end.‘ úThis“restriction“permits“an“alternate“implementationŽ¡that–?ýboth“reduces“memory“usage“and“enables“fast,“direct“access“to“members“by“integer“offset.Ž¡It–?ýobtains“key“performance“advantages“of“an“array“while“preserving“the“dynamic“extendabilityŽ¡of–?ýa“list.ŽŸ33ïhtml:ï html:¦ïhtml:ï html:ŸÅList‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ™N‘0Â-–ff(void)“addFirst:“anObject;Ž¤Òn‘0-–ff(void)“addLast:“anObject;Ž¡¿The–?ýaddFirst:› úand“addLast:˜messages“add“a“new“member“to“either“end“of“a“list.˜With“addFirst:,Ž©the–?ýnew“member“becomes“the“first“member“of“the“array.‘ úWith“addLast:,“it“becomes“the“last“member.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:Ÿ ™Š‘0Â-‘ffremoveFirst;Ž¡‘0-‘ffremoveLast;Ž¡¿removeFirst–?ýand“removeLast“remove“either“the“first“or“last“member“of“a“list.‘ úThey“each“returnŽ¦the–?ývalue“of“the“member“just“removed.ŽŸ8äïhtml:ï html:Ÿffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹vÆ] “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅListIndex‘™™beha£×viorŽºâŸÜ÷ïhtml:ï html:ŸÆà‘0Â//Ž¤‘0//–ffListIndex“--“index“with“insertion“capability“at“any“point“in“listŽ¡‘0//Ž¡‘0@deftype–ffListIndex“-“(void)“addAfter:“anObject;Ž¡‘0-–ff(void)“addBefore:“anObject;Ž¡‘0@endŽ¡¿The–?ýaddAfter:› úand“addBefore:˜messages“add“members“at“a“particular“point“in“the“sequence“ofŽ¡members–?ýmaintained“by“a“list.‘ úThe“current“location“of“an“index“determines“the“point“at“whichŽ¡a–?ýnew“member“will“be“added.› úThe“addAfter:˜message“adds“a“member“at“the“list“position“immediatelyŽ¡following–?ýthe“current“index“location.– úaddBefore:“adds–?ýa“member“to“the“immediately“precedingŽ¡location.‘ úNeither–?ýmessage“changes“the“current“location“of“the“index,“except“that“an“indexŽ¡can–?ýchange“from“a“Start“or“End“location“to“a“location“of“Between.Ž©8äïhtml:ï html:Ÿ Ç‘0Since–?ýan“index“may“be“positioned“to“any“location“in“a“list,“these“messages“enableŽ¡‘0the–?ýconstruction“of“any“desired“sequence“of“members.‘ úSince“the“current“index“locationŽ¡‘0remains–?ýunchanged,“multiple“members“may“all“be“inserted“successively“at“some“pointŽ¡‘0in–?ýa“list;“previously“added“members“are“just“pushed“out“one-by-one“as“new“membersŽ¡‘0are‘?ýadded.ŽŸïhtml:ï html:¡‘0An–?ýindex“with“a“location“of“Start,“End,“or“Between“is“just“as“valid“a“location“forŽ¡‘0addAfter:– úor›?ýaddBefore:“as˜an˜index˜positioned˜at˜a˜member.“In˜these˜cases,˜thereŽ¡‘0is–?ýno“member“at“the“current“location“of“the“index,“so“the“new“member“is“just“insertedŽ¡‘0directly–?ýat“the“current“index“location,“and“the“index“is“left“positioned“between“theŽ¡‘0new–?ýmember“and“the“member“that“was“previously“adjacent“in“the“opposite“direction.Ž¡‘0If–?ýthe“previous“location“was“Start“and“the“message“addAfter:,“or“the“location“wasŽ¡‘0End–?ýand“the“message“addBefore:,“the“index“location“remains“Start“or“End.Ž¦ïhtml:ï html:Ÿ Ç‘0If–?ýeither“the“addAfter:› úor“addBefore:˜message“is“requested“with“the“EndsOnly“option,Ž¡‘0and–?ýthe“index“location“is“not“Start“or“End,“or“if“remove“is“requested“on“an“indexŽ¡‘0that–?ýis“not“positioned“at“either“the“first“or“last“member,“an“invalid“operation“errorŽ¡‘0is‘?ýraised.ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹wÑo “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸËÅStack,–™™Queue“{“r½«estricted“f£×orms“of“listsŽŸ3üïhtml:ï html:Ÿ Š…‘0¿(..› úNeither–?ýof“these“types“is“currently“implemented.˜They“are“nothing“more“thanŽŸ‘0restricted–?ýcases“of“a“List,“so“if“you“need“them“use“a“List“instead.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ©G®ïhtml:ï html:Ÿ×ÀSynopsisŽŸ âcïhtml:ï html:Ÿ–|‘0Â//–ffStack“--“form“of“list“with“add/remove“both“at“start“of“listŽ¤ª‘0//Ž¡‘0@deftype–ffStack“-“(void)“push:“anObject;Ž¡‘0-‘ffpop;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffQueue“--“form“of“list“with“add“at“start“of“list“and“remove“at“lastŽ¡‘0//Ž¡‘0@deftype–ffQueue“-“(void)“enqueue:“anObject;Ž¡‘0-‘ffdequeue;Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:Ÿ×ÀDescriptionŽŸxß¿A–?ýStack“is“a“subtype“of“List“which“restricts“the“addition“and“removal“of“members“to“the“startŽ¤of–?ýa“list.‘ úQueue“is“a“subtype“of“List“which“restricts“addition“of“members“to“the“start“ofŽ¡the–?ýlist“and“removal“to“the“end.‘ úBoth“types“define“specially“named“messages“to“reflect“theŽ¡specialized–?ýusage“of“their“resulting“add“and“remove“operations.ŽŸ—ïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:Ÿ×ÀInterface‘QëRefer°genceŽŸªóïhtml:ï html:ŸËÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸáŠ‘0Â@deftype–ffStack“@deftype“Queue“ŽŸª¿...ŽŸïhtml:ï html:Ÿffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹xÜo “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅStack‘™™beha£×viorŽºâŸÜ÷ïhtml:ï html:ŸÆà‘0Â-–ff(void)“push:“anObject;Ž¤‘0-‘ffpop;Ž¡¿...Ž©ïhtml:ï html:Ÿffïhtml:ï html:ŸG®ÅQueue‘™™beha£×viorŽŸ3üïhtml:ï html:Ÿ oÛ‘0Â-–ff(void)“enqueue:“anObject;Ž¡‘0-‘ffdequeue;Ž¡¿...Ž¦ïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹yã£ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ3ÅK•£×eyšÛ$edCollection,‘™™K“ey˜edIndex–™™{“supertype“of“Set“and“Map“typesŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¾|ÀSynopsisŽŸ âcïhtml:ï html:Ÿ}ä‘0Â//Ž¤‘0//–ffKeyedCollection“--“supertype“of“Set“and“Map“typesŽ¡‘0//Ž¡‘0@deftype–ffKeyedCollection“CREATINGŽ¡‘0-–ff(void)“setDuplicatesOption:“duplicatesOption;Ž¡‘0-–ff(void)“setGroupType:“aCollectionType;Ž¡‘0-–ff(void)“setSingletonGroups:“(BOOL)singletonGroups;Ž¡¡‘0-–ff(void)“setSorted:“(BOOL)sorted;Ž¡‘0-–ff(void)“setCompareFunction:“(idXid_t)aFunction;Ž¡‘0-ŽŸ‘0(void)‘+30setBucketFunction:–ff(bucket_t)aFunction“setBucketCount:“(int)n;Ž¡¡‘0-–ff(void)“setPartiallyOrdered:“(BOOL)partiallyOrdered;Ž¡‘0-–ff(void)“setMemberSlot:“(int)byteOffset;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setPartialOrderContext:“aKeyedCollectionCollection;Ž¡‘0USINGŽ¡‘0-‘ffgetDupOption;Ž¡‘0-‘ffgetGroupType;Ž¡‘0-–ff(BOOL)“getSingletonGroups;Ž¡¡‘0-–ff(BOOL)“getSorted;Ž¡‘0-–ff(int(*)())“getCompareFunction;Ž¡‘0-–ff(int(*)())“getBucketFunction;Ž¡‘0-–ff(int)“getMaxBuckets;Ž¡¡‘0-–ff(BOOL)“getPartiallyOrdered;Ž¡‘0-‘ffgetPartialOrderContext;Ž¡¡‘0-–ff(int)“getMemberSlot;Ž¡¡‘0-–ffat:“aKey;Ž¡‘0-–ff(BOOL)“containsKey:“aKey;Ž¡‘0-–ff(int)“getCountAtKey:“aKey;Ž¡¡‘0-–ffremoveKey:“aKey;Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹zæê “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ-–ffcreateIndex:“aZone“at:“aKey;Ž¤ ’‘/ºâ-–ffcreateIndex:“aZone“setMember:“aMember;Ž¡¡‘/ºâ-–ff(void)“getPredecessors:“aMember;Ž¡‘/ºâ-–ff(void)“getSuccessors:“aMember;Ž¡‘/ºâ-–ff(void)“getCostarts:“aMember;Ž¡‘/ºâ-–ff(void)“getCoends:“aMember;Ž¡‘/ºâ@endŽ¡¡‘/ºâ//Ž¡‘/ºâ//–ffKeyedIndex“--“index“behavior“shared“by“Set“and“Map“typesŽ¡‘/ºâ//Ž¡‘/ºâ@deftype–ffKeyedIndex“Ž¡‘/ºâ-–ff(int)“getCurrentLevel;Ž¡‘/ºâ-–ffgetIndexAtLevel:“(int)level;Ž¡¡‘/ºâ-–ffat:“aKey;Ž¡¡‘/ºâ-–ffsetMember:“aMember;Ž¡‘/ºâ@endŽŸ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:ŸÐüÀDescriptionŽŸrÇ¿A–?ýkeyed“collection“is“a“collection“in“which“each“member“can“be“compared“with“some“other“valueŽ¤that–?ýidentifies“the“member.› úThis“value“is“referred“to“as“the“member“key.˜The“key“value“mayŽ¡be–?ýdetermined“either“by“the“member“value“itself,“which“defines“a“Set,“or“by“external“associationŽ¡with–?ýthe“member“when“the“member“is“first“added,“which“defines“a“Map.ŽŸ—ïhtml:ï html:© Û®‘0The–?ýkeyed“collection“type“establishes“the“common“behavior“shared“by“both“Set“and“Map.Ž¡‘0Standard–?ýoptions“are“provided“to“declare“ordering“of“members“in“the“collection,“whichŽ¡‘0can–?ýbe“based“either“on“an“inherent“ordering“of“the“key“values“(a“sorted“collection)Ž¡‘0or–?ýexternal“maintenance“of“a“total“or“partial“order.‘ úAdditionally,“options“are“providedŽ¡‘0to–?ýdeclare“whether“duplicate“key“values“should“be“permitted,“and“if“so,“how.ŽŸ8äïhtml:ï html:¦‘0The–?ýoptions“for“handling“of“duplicate“keys“provide“considerable“flexibility.‘ úEntireŽ¡‘0structures–?ýof“nested“collections“can“be“created“that“subdivide“the“key“space“throughŽ¡‘0progressive–?ýlevels.‘ úBy“accepting“duplicate“keys,“and“organizing“members“of“the“sameŽ¡‘0identity–?ýinto“subgroups,“keyed“collections“support“the“abstract“data“type“known“asŽ¡‘0a–?ýbag“or“multiset.‘ úThe“index“on“a“keyed“collection“includes“the“ability“to“traverseŽ¡‘0throughout–?ýthe“contents“of“any“of“these“nested“collections.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹{íZ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅInherited‘™™beha£×viorŽºâŸÜ÷ïhtml:ï html:Ÿ¨Ý‘0Â@deftype–ffKeyedCollection“ŽŸáý¿The–?ýKeyedCollection“type“inherits“all“standard“behavior“of“Collection.‘ úThe“KeyedCollectionŽ¤type–?ýis“not“itself“creatable;“it“only“serves“as“a“common“supertype“for“Set“and“Map“collectionŽ¡types.Ž©8äïhtml:ï html:Ÿ ©‘0The–?ýdefault“value“of“IndexSafety“for“a“KeyedCollection“is“Unsafe,“but“values“of“eitherŽ¡‘0UnsafeAtMember–?ýor“SafeAlways“can“be“requested“to“guarantee“a“higher“level“of“safety.Ž¦ïhtml:ï html:Ÿffïhtml:ï html:ŸðÇÅCr½«eate-time‘™™optionsŽŸ…Ô¿(..‘ úNone–?ýof“these“options“is“implemented“yet,“except“for“CompareFunction.)ŽŸ Ü»ïhtml:ï html:Ÿïhtml:ï html:Ÿ ©‘0ÂCREATINGŽ¤áý‘0-–ff(void)“setDupOption:“dupOption;Ž¡‘0-–ff(void)“setGroupType:“aCollectionType;Ž¡‘0-–ff(void)“setSingletonGroups:“singletonGroups;Ž¡¡‘0-–ff(void)“setSorted:“(BOOL)sorted;Ž¡‘0-–ff(void)“setCompareFunction:“(idXid_t)aFunction;Ž¡¡‘0-–ff(void)“setPartiallyOrdered:“(BOOL)partiallyOrdered;Ž¡¡‘0-–ff(void)“setMemberSlot:“(int)byteOffset;Ž¡‘0SETTINGŽ¡‘0-ŽŸ‘0(void)‘+30setBucketFunction:–ff(bucket_t)aFunction“setBucketCount:“(int)n;Ž¡‘0-–ff(void)“setPartialOrderContext:“aKeyedCollection;Ž¡‘0USINGŽ¡‘0-‘ffgetDupOption;Ž¡‘0-‘ffgetGroupType;Ž¡‘0-–ff(BOOL)“getSingletonGroups;Ž¡¡‘0-–ff(BOOL)“getSorted;Ž¡‘0-–ff(int(*)())“getCompareFunction;Ž¡¡‘0-–ff(BOOL)“getPartiallyOrdered;Ž¡‘0-‘ffgetPartialOrderContext;Ž¡¡‘0-–ff(int)“getMemberSlot;Ž¡¡‘0-–ff(int(*)())“getBucketFunction;Ž¡‘0-–ff(int)“getBucketCount;ŽŸ bÌïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹|öœ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÊDupOptionŽŸ.vºâ¿The–?ývalue“of“DupOption“specifies“how“duplicate“key“values“are“to“be“handled“within“a“keyedŽ¤ºâcollection.‘ úThis–?ýoption“has“one“of“the“following“values:ŽºâŸ lïhtml:ï html:© Â_‘0Âid–ff‘ ÌÌDupIsError,“DupRejected,“KeepDuplicates,“KeepCountOnly;ŽŸûC¿If–?ýthe“DupIsError“value“is“specified,“any“attempt“to“insert“a“duplicate“key“is“an“error,“andŽ¡effects–?ýof“such“an“attempt“depend“on“the“level“of“debug“checking.‘ úIf“debug“checking“for“thisŽ¡error–?ýis“turned“on,“the“collection“will“check“whether“any“new“key“duplicates“an“existing“one,Ž¡and–?ýraise“a“DuplicateKey“error“if“it“does.‘ úIf“debug“checking“is“turned“off,“there“is“no“guaranteeŽ¡that–?ýany“check“will“be“made,“and“the“effects“could“be“unpredictable“in“or“catastrophic“or“insidiousŽ¡ways.ŽŸ8äïhtml:ï html:¦‘0With–?ýa“value“of“DupRejected,“attempts“to“insert“a“duplicate“key“are“always“detected,Ž¡‘0and–?ýthe“attempt“rejected.‘ ú(All“insert“messages“return“a“boolean“flag“as“to“whetherŽ¡‘0a–?ýduplicate“occurred.)ŽŸ8äïhtml:ï html:¦‘0With–?ýa“value“of“KeepDuplicates,“attempts“to“insert“a“duplicate“key“are“always“accepted,Ž¡‘0and–?ýall“members“having“the“same“key“are“retained“in“a“specially“created“internal“collectionŽ¡‘0containing–?ýjust“the“members“that“all“have“that“same“key.‘ úThis“collection“then“becomesŽ¡‘0the–?ýsingle“member“internally“associated“with“the“key“value.ŽŸ8äïhtml:ï html:¦‘0With–?ýa“value“of“KeepCountOnly,“duplicate“members“are“not“retained.‘ úInstead,“onlyŽ¡‘0a–?ýcount“of“the“net“number“of“insertions“and“removals“at“that“key“value“are“retainedŽ¡‘0within–?ýthe“collection.‘ úWith“this“value,“member“values“cannot“be“retrieved“from“theŽ¡‘0collection,–?ýbut“only“a“count“of“members“for“a“given“key“value,“using“different“messages.Ž¡‘0This–?ývalue“is“accepted“only“for“the“Set“subtype“of“a“KeyedCollection.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:Ÿ (Å‘0ÊGrÈ¹oupT‘ÿ¬ypeŽŸ.v¿The–?ýGroupType“option“specifies“the“type“of“internal“collection“to“be“created“for“members“thatŽ¡all–?ýhave“the“same“key.‘ úThis“option“is“valid“only“if“DupOption“is“also“set“to“a“value“of“KeepDuplicates.ŽŸ lïhtml:ï html:¦‘0Without–?ýthis“option,“the“type“of“internal“collection“created“for“members“with“theŽ¡‘0same–?ýkey“depends“on“the“specific“subtype.‘ úThis“option“allows“an“external“programŽ¡‘0to–?ýcustomize“the“type“of“internal“collection“permitted.‘ úThe“argument“must“be“a“previouslyŽ¡‘0created–?ýsubtype“of“Collection.‘ úTypically,“the“argument“is“a“customized“version“ofŽ¡‘0one–?ýof“the“standard“collection“types“such“as“List,“Set,“or“Map;“the“argument“wouldŽ¡‘0be–?ýthe“type“object“returned“by“customizeEnd“after“a“customizeBegin:‘ úsequence.ŽŸ8äïhtml:ï html:¦‘0More–?ýinformation“about“all“the“ways“this“option“can“be“interpreted“is“provided“withŽ¡‘0each‘?ýsubtype.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:Ÿ (Å‘0ÊSingletonGrÈ¹oupsŽŸ.v¿If–?ýthis“option“is“true,“the“type“of“collection“created“for“members“with“duplicate“keys“is“alsoŽ¡created–?ýeven“when“there“is“only“member“for“a“particular“key.‘ úThis“option“can“be“convenientŽ¡to–?ýassure“uniformity“of“a“keyed“collection“with“nested“structure.‘ úThis“option“is“valid“onlyŽ¡if–?ýDupOption“is“also“set“to“a“value“of“KeepDuplicates.ŽŸ lïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹}þG “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0ÊSortedŽ©ë…¿If–?ýthis“option“is“true,“the“immediate“members“of“a“keyed“collection“(included“collections“ofŽ¤duplicate–?ýmembers,“if“any)“are“totally“ordered“according“to“an“ordering“relation“defined“onŽ¡key–?ývalues.› úThe“default“order“for“sorting“is“determined“by“a“standard“compare:˜message“onŽ¡a–?ýkey“value“to“be“added“vs.› úexisting“keys“of“the“collection.˜This“default“method“to“establishŽ¡order–?ýcan“be“overridden“using“the“CompareFunction“option.ŽŸ lïhtml:ï html:Ÿ n‘0The–?ýdefault“for“the“Sorted“function“is“true,“unless“a“value“is“also“given“for“theŽ¡‘0option‘?ýBucketFunction.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:ŸåÔ‘0ÊComparÈ¹eFunctionŽ¦¿Use–?ýthe“function“pointed“to“by“the“argument“as“the“method“for“determining“whether“two“membersŽ¡have–?ýthe“same“key“value,“and“also“for“ordering“the“keys“of“the“collection“if“the“Sorted“optionŽ¡is–?ýtrue.‘ úThe“argument“is“declared“with“the“following“function“pointer“type:ŽŸ lïhtml:ï html:© n‘0Âtypedef–ffint“(*idXid_t)(“id,“id“);ŽŸ¸R¿The–?ýfunction“given“will“be“called“whenever“one“key“value“needs“to“be“compared“with“another.Ž¡Multiple–?ýcalls“to“the“function“typically“occur“whenever“members“are“added“or“removed“from“theŽ¡collection,–?ýuntil“the“correct“member“for“insertion“or“removal“is“determined.ŽŸcïhtml:ï html:ŸTÅ‘0The–?ýcompare“function“accepts“two“key“values“as“its“arguments.‘ úLike“member“types,Ž¡‘0key–?ýtypes“declared“with“the“id“pointer“type,“but“may“contain“any“type“of“value“(suchŽ¡‘0as–?ýan“integer)“up“to“the“size“of“an“id.‘ úAn“explicit“compare“function“can“supportŽ¡‘0any–?ýtype“of“value“as“a“key,“regardless“of“whether“it“is“an“object“that“supports“aŽ¡‘0standard‘?ýcompare:‘ úmessage.ŽŸ8äïhtml:ï html:¦‘0The–?ýcompare“function“is“called“repeatedly“by“the“collection“to“compare“two“key“values.Ž¡‘0The–?ýfunction“should“return“zero“if“the“key“values“are“equal,“-1“for“the“first“keyŽ¡‘0argument–?ýless“than“the“second,“and“+1“for“the“first“greater“than“the“second.‘ úIf“aŽ¡‘0keyed–?ýcollection“is“not“sorted,“either“-1“or“+1“may“be“returned“for“unequal“keys,Ž¡‘0regardless–?ýof“whether“one“might“be“taken“as“greater“or“less“than“the“other.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:ŸåÔ‘0ÊBuckáIetFunctionŽŸë…¿The–?ýBucketFunction“option“specifies“a“function“that“is“called“whenever“a“member“of“an“unsortedŽ¡collection–?ýis“added“or“removed.‘ úIt“may“also“be“used“for“a“sorted“collection“to“provide“fasterŽ¡insertion–?ýand“removal“of“members.‘ úThe“responsibility“of“a“"bucket“function"“is“to“assign“theŽ¡key–?ývalue“to“some“integer“in“a“range“from“zero“up“to“some“maximum“value.‘ úThese“integers“identifyŽ¡"buckets"–?ýto“which“the“same“key“value“will“also“be“assigned“whenever“passed“to“the“function.Ž¡If–?ýthe“collection“is“unsorted,“these“buckets“represent“hash“buckets,“and“for“speed“should“beŽ¡relatively–?ýsparse“(few“keys“likely“in“any“one“bucket,“given“the“expected“size“of“the“collection).Ž¡If–?ýthe“collection“is“sorted,“these“buckets“represent“ordered“buckets“to“which“the“same“rangeŽ¡of–?ýkey“values“will“always“be“assigned.‘ úSuch“sorted“buckets“can“speed“up“the“search“for“a“keyŽ¡location–?ýwithin“a“sorted“collection.‘ úSorted“buckets“can“also“be“sparse“to“minimize“the“needŽ¡for–?ýfurther“sorting“within“each“bucket.‘ úIf“many“keys“end“up“in“the“same“sorted“bucket,“theŽ¡sorting–?ýprocess“normally“used“without“buckets“is“still“used,“so“there“is“less“performance“impactŽ¡than–?ýwith“hash“keys“of“an“unsorted“collection.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹~ß “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0¿A–?ýbucket“function“accepts“a“single“key“value“as“its“argument,“and“return“an“integerŽ¤‘0that–?ýidentifies“a“bucket.‘ úAs“with“a“compare“function,“the“key“value“is“declared“asŽ¡‘0an–?ýid“pointer“type,“but“may“actually“contain“whatever“kind“of“value“is“used“withinŽ¡‘0the–?ýcollection.‘ úFollowing“is“the“type“of“the“bucket“function“pointer:Ž©8äïhtml:ï html:Ÿïhtml:ï html:Ÿjb‘0Âtypedef–ffint“(*bucket_t)(“id“);ŽŸ£F¿A–?ýnew“bucket“function“may“be“established“any“time“during“the“lifetime“of“a“collection.‘ úA“newŽ¡bucket–?ýfunction“can“ensure“that“keys“remain“suitably“distributed“to“buckets“as“the“total“numberŽ¡of–?ýkeys“in“a“collection“grows“or“shrinks.Ž¦ïhtml:ï html:¡ïhtml:ï html:©ÐÈ‘0ÊBuckáIetCountŽŸÖy¿A–?ývalue“for“MaxBuckets“must“be“given“in“the“same“message“that“sets“a“bucket“function.‘ úItsŽ¡value–?ýspecifies“the“number“of“buckets“to“which“a“bucket“function“assigns“its“keys.‘ úThe“maximumŽ¡value–?ýreturned“by“a“bucket“function“should“be“one“less“than“this“value.ŽŸ lïhtml:ï html:¡ïhtml:ï html:¦‘0ÊPáIartiallyOrderÈ¹edŽŸÖy¿A–?ýpartially“ordered“collection“supports“the“maintenance“of“individual“ordering“relations“amongŽ¡its–?ýmembers.‘ úEach“such“relation“is“an“assertion“that“one“member“should“always“precede“anotherŽ¡in–?ýthe“enumeration“sequence“of“the“collection.‘ úWhen“an“index“traverses“the“collection,“itŽ¡will–?ýguarantee“that“all“the“predecessors“of“a“member“have“already“been“visited“before“the“memberŽ¡itself–?ýis“reached.ŽŸ33ïhtml:ï html:Ÿ£F‘0If–?ýtrue,“PartiallyOrdered“specifies“that“messages“for“maintaining“a“partial“orderŽ¡‘0are–?ýenabled“on“the“collection.‘ úAn“error“will“be“raised“if“individual“members“do“notŽ¡‘0have–?ýa“unique“identity“within“the“innermost“collection“within“which“they“are“contained.Ž¡‘0This–?ýmeans“that“if“duplicate“keys“are“permitted“by“the“collection,“a“collection“typeŽ¡‘0must–?ýalso“be“specified“for“GroupType“which“does“not“itself“accept“duplicates.‘ úEveryŽ¡‘0member–?ýin“a“partial“order“must“have“a“unique“identity“so“that“the“member“itself“isŽ¡‘0sufficient–?ýto“identify“it“within“the“network“of“partial“orders.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:¦‘0ÊP•áIartialOrderContext:‘¸PaK³3ey“edCollectionCollectionŽŸÖy¿Ordering–?ýrelations“may“be“maintained“not“only“between“members“belonging“to“the“same“collection,Ž¡but–?ýbetween“members“and“other“collections,“as“long“as“all“participants“in“an“ordering“are“containedŽ¡somewhere–?ýwithin“a“larger“common“collection.‘ úAn“ordering“relation“with“a“nested“collectionŽ¡specifies–?ýthat“all“members“in“the“collection“are“successors“or“predecessors“of“the“other“member.Ž¡Ordering–?ýrelations“can“also“be“established“between“members“of“a“larger,“containing“collection,Ž¡and–?ýindividual“members“of“a“nested“collection.ŽŸ33ïhtml:ï html:Ÿ£F‘0The–?ýkeyed“collection“specified“as“the“value“for“PartialOrderContext“must“specify“anotherŽ¡‘0collection–?ýin“which“the“local“collection“is“maintained.‘ úIt“is“an“error“if“the“PartialOrderContextŽ¡‘0collection–?ýdoes“not“actually“contain“the“local“collection.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹1 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÊgetMemberSlotŽŸ¦@ºâ¿The–?ýMemberSlot“option“indicates“that“space“has“been“reserved“within“each“member“that“allowsŽ¤ºâit–?ýto“contain“a“link“directly“to“its“position“in“the“enumeration“for“a“collection.‘ úIf“suchŽ¡ºâspace–?ýhas“been“reserved,“special“messages“can“be“used“that“rapidly“position“an“index“directlyŽ¡ºâto–?ýthe“member.‘ úOperations“to“remove“members“are“also“much“faster.ŽºâŸ lïhtml:ï html:© :)‘0The–?ývalue“of“MemberSlot“specifies“the“offset“in“bytes“from“the“start“of“each“memberŽ¡‘0where–?ýthe“space“for“its“position“link“has“been“reserved.‘ úThe“following“typedefs“areŽ¡‘0provided–?ýto“declare“the“space“required“for“a“position“link“within“a“member“allocation:ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0Âtypedef–ffstruct“memberData“Çf“Âvoid“*memberData[2];“Çg‘@ÌÈÂmember_t;Ž¤s ‘0typedef–ffstruct“memberData“Çf“Âvoid“*memberData[2];“id“owner;“Çg‘ ÌÌÂdupmember_t;Ž¡¿The–?ýfirst“type“declares“the“required“space“for“a“position“link“in“a“collection“that“does“notŽ¤accept–?ýduplicate“key“values.‘ úThe“second“type“is“required“if“duplicate“keys“are“permitted.ŽŸ8äïhtml:ï html:¦‘0The–?ýoffset“of“the“position“link“from“the“start“of“a“member“may“be“either“positiveŽ¡‘0or–?ýnegative,“in“the“range“of“-2048“to“+2047.‘ úThe“default“value“of“MemberSlot“is“UnknownOffsetŽ¡‘0(a–?ýlarge“negative“value),“which“specifies“that“no“slot“for“an“internal“position“linkŽ¡‘0is–?ýavailable“within“each“member.ŽŸïhtml:ï html:Ÿs ‘0If–?ýa“member“slot“is“defined,“a“memory“pointer“of“some“kind“must“always“be“used“forŽ¡‘0the–?ývalue“of“every“member.‘ úThese“members“may“be“object“id“pointers,“but“other“typesŽ¡‘0of–?ýmemory“pointers“are“acceptable“as“well.ŽŸ8äïhtml:ï html:¦‘0The–?ýcontents“of“the“first“two“words“of“position“link“vary“according“to“the“positionŽ¡‘0of–?ýa“member“in“a“collection.‘ úThe“third“word“of“a“dupmember_t“link“contains“the“idŽ¡‘0of–?ýthe“collection“in“which“a“member“is“directly“contained.‘ úThis“collection“is“eitherŽ¡‘0an–?ýinternally“created“collection“containing“members“with“duplicate“keys,“or“the“collectionŽ¡‘0to–?ýwhich“the“member“was“added“if“there“is“no“other“member“with“the“same“key.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿº»ÅK•£×eyÛ$edCollection‘™™beha“viorŽŸä¿(..‘ úNone–?ýof“the“messages“or“other“behavior“relating“to“duplicate“key“values“are“currentlyŽ¡implemented.)ŽŸ Ü»ïhtml:ï html:¦‘0Â-–ffat:“aKey;Ž¤s ‘0-–ff(BOOL)“containsKey:“aKey;Ž¡‘0-–ff(int)“getCountAtKey:“aKey;‘ ÌÌ//“unimplementedŽ¡¡‘0-–ffremoveKey:“aKey;Ž¡¿The–?ýat:‘ úmessage“returns“the“existing“member“of“the“collection“which“matches“the“key“valueŽ¤passed–?ýas“its“argument,“or“nil“if“there“is“no“key“value“in“the“collection“which“matches.‘ úIfŽ¡duplicate–?ýentries“for“this“key“exist,“the“entire“collection“of“duplicate“members“created“forŽ¡the–?ýkey“value“is“returned“instead.ŽŸ8äïhtml:ï html:¦‘0The–?ýcontainsKey:‘ úmessage“returns“true“if“the“key“value“passed“as“its“argument“isŽ¡‘0contained–?ýin“the“collection,“and“false“otherwise.‘ úThe“getCountAtKey“message“returnsŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹€*Y “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿the–?ýnumber“of“member“entries“which“are“all“associated“with“its“key“value“argument.Ž¤‘/ºâThis–?ýnumber“is“zero“if“the“key“value“is“not“contained“in“the“collection,“and“willŽ¡‘/ºânever–?ýexceed“one“one“unless“a“collection“accepts“duplicate“entries“for“a“key.Žºâ©8äïhtml:ï html:Ÿ ÛØ‘0The–?ýremoveKey:‘ úmessage“removes“a“member“matching“a“key“value“from“the“collection,Ž¡‘0and–?ýreturns“the“member“just“removed.‘ úIt“returns“nil“if“there“is“no“key“value“in“theŽ¡‘0collection–?ýwhich“matches.‘ úIf“more“than“one“entry“was“present“for“the“key“value,“itŽ¡‘0removes–?ýand“returns“the“first“member“in“the“internal“collection“created“for“duplicateŽ¡‘0members.Ž¤ïhtml:ï html:¡ïhtml:ï html:¤¼‘0Â-–ffcreateIndex:“aZone“at:“aKey;Ž¡‘0-–ffcreateIndex:“aZone“setMember:“aMember;Ž¡¿(..‘ úNeither–?ýof“these“messages“is“currently“implemented.)Ž¦ïhtml:ï html:Ÿ ÛØ‘0The–?ýcreateIndex:at:‘ úmessage“creates“a“new“index“on“the“collection“and“also“sets“itsŽ¤‘0current–?ýposition“to“the“first“member“matching“the“key“value“given“as“its“final“argument.Ž¡‘0It–?ýreturns“the“index“just“created.Ž¦ïhtml:ï html:Ÿ ÛØ‘0The–?ýcreateIndex:at:‘ úmessage“creates“a“new“index“on“the“collection“and“also“sets“itsŽ¡‘0current–?ýposition“to“the“member“passed“as“its“final“argument.‘ úThis“message“is“validŽ¡‘0only–?ýif“an“internal“member“slot“was“defined“for“the“collection“with“the“MemberSlotŽ¡‘0option.Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ ÛØ‘0Â-–ff(void)“getPredecessors:“aMember;Ž¤¼‘0-–ff(void)“getSuccessors:“aMember;Ž¡‘0-–ff(void)“getCostarts:“aMember;Ž¡‘0-–ff(void)“getCoends:“aMember;Ž¡¿(..› úNone–?ýof“these“messages“is“currently“implemented.)˜These“messages“maintain“the“orderingŽŸrelations–?ýwithin“a“partially“ordered“collection.Ž¦ïhtml:ï html:Ÿffïhtml:ï html:Ÿ#†ÅK•£×eyÛ$edIndex‘™™beha“viorŽŸ‘ýïhtml:ï html:Ÿ &–‘0Â-–ff(int)“getCurrentLevel;Ž¡‘0-–ffgetIndexAtLevel:“(int)level;Ž¡¿An–?ýindex“to“a“keyed“collection“traverses“all“members“of“the“collection,“regardless“of“whetherŽ¤these–?ýmembers“belong“to“collections“of“members“entered“under“duplicate“key“values.‘ úInternally,Ž¡however,–?ýan“index“keeps“track“of“any“specific“subcollection“it“is“currently“processing.‘ úTheŽ¡getCurrentLevel–?ýmessage“returns“the“level“of“nesting,“within“collections“of“duplicate“entriesŽ¡for–?ýa“current“key“value,“to“which“the“current“position“of“an“index“belongs.‘ úThe“level“returnedŽ¡is–?ýan“integer“that“starts“at“zero“for“the“top-level“collection,“and“increases“by“one“for“eachŽ¡level–?ýof“nested“collection“that“is“currently“active.Ž¦ïhtml:ï html:Ÿ ÛØ‘0While–?ýprocessing“any“nested“collections,“the“index“for“a“keyed“collection“actuallyŽ¡‘0maintains–?ýa“separate,“internal“index“for“each“level“of“collection“that“is“currentlyŽ¡‘0active.› úThe–?ýindex“at“each“level“may“be“retrieved“using“the“getIndexAtLevel:˜message.Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ ÛØ‘0Â-–ffat:“aKey;ŽŸ¼¿The–?ýat:‘ úmessage“repositions“the“index“to“the“first“member“that“matches“the“key“value“passedŽ¡as–?ýits“argument.Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹8 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:© ‘0Â-–ffsetMember:“aMember;Ž¤¿(..› úThis–?ýmessage“is“not“currently“implemented.)˜The“setMember:˜message“repositions“the“indexŽ¡to–?ýthe“member“passed“as“its“argument.‘ úThis“message“is“valid“only“if“an“internal“member“slotŽ¡was–?ýdefined“for“the“collection“with“the“MemberSlot“option.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¾Roger–?ýBurkhart“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:rmb@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last–?ýmodified:‘ ú1997-12-19“(mgd)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹‚F& “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸŠÅSet–™™{“collection“of“members“each“ha£×ving“a“dened“identityŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸÑÓÀSynopsisŽŸ âcïhtml:ï html:Ÿ‘;‘0Â//Ž¤i‘0//–ffSet“--“collection“of“members“each“having“a“defined“identityŽ¡‘0//Ž¡‘0@deftype–ffSet“CREATINGŽ¡‘0-–ff(void)“setKeyFunction:“(id“(*)(id))aFunction;Ž¡‘0USINGŽ¡‘0-–ff(id“(*)(id))“getKeyFunction;Ž¡¡‘0-–ff(BOOL)“add:“anObject;Ž¡‘0-–ff(BOOL)“add:“anObject“setIndex:“anIndex;Ž¡‘0-–ffreplace:“anObject;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸÑÓÀDescriptionŽŸsž¿Set–?ýis“a“subtype“of“KeyedCollection“in“which“the“key“value“associated“with“each“member“is“determinedŽ¤by–?ýthe“member“value“itself.‘ úThe“key“value“may“be“identical“to“the“member“itself,“or“may“beŽ¡defined–?ýas“a“a“function“of“the“member“using“a“create-time“option.ŽŸ—ïhtml:ï html:©ffïhtml:ï html:Ÿ$3ÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸÜI‘0Â@deftype–ffSet“ŽŸi¿The–?ýSet“type“inherits“most“of“its“interface“from“the“KeyedCollection“supertype.‘ úSet“definesŽ¡no–?ýcreate-time“options“beyond“those“already“defined“by“KeyedCollection.‘ úIf“a“custom“compareŽ¡or–?ýbucket“function“is“specified,“the“member“value“is“passed“as“the“key“value“arguments“of“theseŽ¡functions.‘ úThese–?ýfunctions“determine“what“part“of“the“member“value“is“part“of“the“key“value,Ž¡by–?ýdetermining“which“key“values“will“compare“equal“to“any“member.ŽŸ8äïhtml:ï html:¦ïhtml:ï html:Ÿ$3ÅSet‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸÜI‘0Â-–ff(BOOL)“add:“anObject;Ž¤i‘0-–ff(BOOL)“add:“anObject“setIndex:“anIndex;Ž¡‘0-–ffreplace:“anObject;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ƒIz “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ@endŽ¤ºâ¿The–?ýadd:› úmessage“adds“a“new“member“to“a“set.˜It“returns“true“if“member“added“matched“theŽ¡ºâkey–?ýof“any“member“already“contained“in“the“Set.‘ úWhether“or“not“the“member“was“actually“addedŽ¡ºâto–?ýthe“collection“or“not“depends“on“the“setting“of“DupOption.Žºâ©8äïhtml:ï html:Ÿ Ç‘0The–?ýadd:setIndex:‘ úmessage“adds“a“new“member“to“a“set“just“like“add:,“but“also“hasŽ¡‘0a–?ýside“effect“of“setting“the“position“of“the“index“passed“as“the“setIndex:‘ úargumentŽ¡‘0to–?ýthe“member“which“was“just“added.‘ úIf“an“index“positioned“to“the“new“member“is“neededŽ¡‘0anyway,–?ýsetting“the“index“in“the“same“operation“avoids“repeating“a“search“for“theŽ¡‘0position–?ýat“which“the“member“key“belongs.Ž¦ïhtml:ï html:Ÿ Ç‘0The–?ýreplace:‘ úmessage“replaces“a“member“stored“at“a“given“key“with“another“memberŽ¡‘0value–?ýthat“matches“the“same“key.‘ úThe“new“value“to“replace“the“existing“one“is“passedŽ¡‘0as–?ýthe“argument.– úreplace:“returns–?ýthe“member“value“that“was“replaced,“or“nil“ifŽ¡‘0the–?ýcollection“contained“no“member“with“a“matching“key.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹„Q¾ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ!ÅOrder½«edSet–™™{“set“of“members“in“an“exterÈ½nally“assigned“linear“sequenceŽŸ‘ýïhtml:ï html:Ÿ Ú‘0¿(..‘ úThis–?ýtype“is“currently“implemented“only“using“the“low-level“option“of“an“internalŽ¤‘0member–?ýslot,“and“the“messages“for“that“option“do“not“match“the“documentation“in“KeyedCollection.Ž¡‘0If–?ýyou“need“one“of“these“objects,“then“either“use“a“List“or“wait“for“some“other“implementation.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ©G®ïhtml:ï html:Ÿ¼jÀSynopsisŽŸ âcïhtml:ï html:Ÿ{Ò‘0Â//Ž¡‘0//–ffOrderedSet“--“set“of“members“in“an“externally“assigned“linear“sequenceŽ¡‘0//Ž¡‘0@deftype–ffOrderedSet“@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:Ÿ¼jÀDescriptionŽŸ^5¿An–?ýOrderedSet“is“a“totally“ordered“collection“of“members“in“which“every“member“also“has“a“distinctŽ¡identity–?ýas“defined“by“comparison“against“a“key“value.ŽŸ—ïhtml:ï html:Ÿffïhtml:ï html:ŸÊÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸÆà‘0Â@deftype–ffOrderedSet“Ž¡¿The–?ýsequence“of“members“of“an“OrderedSet“is“established“using“the“same“messages“that“maintainŽ¡member–?ýsequence“in“a“List.‘ úAn“OrderedSet“supports“customization“and“access“by“key“as“definedŽ¡by–?ýSet“and“KeyedCollection.‘ úThe“union“of“messages“from“all“these“sources“defines“the“totalŽ¡interface–?ýof“an“OrderedSet.‘ úMembers“with“duplicate“keys,“however,“are“not“valid“for“an“OrderedSet.Ž¡Each–?ýmember“must“have“a“unique“position“within“the“member“sequenceŽ©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹…X4 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ•ÅMap–™™{“collection“of“associations“fr½«om“kÛ$ey“objects“to“member“objectsŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸËÞÀSynopsisŽŸ âcïhtml:ï html:Ÿ‹F‘0Â//Ž¤t‘0//–ffMap“--“collection“of“associations“from“key“objects“to“member“objectsŽ¡‘0//Ž¡‘0@deftype–ffMap“CREATINGŽ¡‘0-–ff(void)“setKeyType:“aDataType;Ž¡‘0-–ff(void)“setKeySlot:“(int)byteOffset;Ž¡‘0USINGŽ¡‘0-‘0™–getKeyType;Ž¡‘0-–ff(int)“getKeySlot;Ž¡¡‘0-–ff(BOOL)“at:“aKey“insert:“anObject;Ž¡‘0-–ff(BOOL)“at:“aKey“insert:“anObject“setIndex:“anIndex;Ž¡‘0-–ffat:“aKey“replace:“anObject;Ž¡¡‘0-–ff(BOOL)“insertGroup:“aKey;Ž¡¡‘0-–ffcreateIndex:“aZone“setKey:“aKey;Ž¡‘0@endŽ¡¡‘0@deftype–ffMapIndex“-“getKey;Ž¡‘0-–ffsetKey:“aKey;Ž¡¡‘0-–ffget:“(id“*)key;Ž¡‘0-–ffnext:“(id“*)key;Ž¡‘0-–ffprev:“(id“*)key;Ž¡¡‘0-–ffreplaceKey:“aKey;Ž¡‘0endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸËÞÀDescriptionŽŸm©¿Map–?ýis“a“subtype“of“KeyedCollection“in“which“the“key“value“associated“with“each“member“is“independentŽ¤of–?ýthe“member“itself.‘ úWhenever“a“new“member“is“added“to“the“collection,“a“key“value“to“beŽ¡associated–?ýwith“the“member“must“be“supplied“also.‘ úA“Map“defines“a“mapping“from“key“valuesŽ¡to–?ýmember“values.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹†a “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0„¤ŽŽ©ffïhtml:ï html:Ÿ³3ÅInherited‘™™beha£×viorŽŸ\¿For–?ýthe“Map“type,“key“values“are“independent“of“the“member“values“with“which“they“are“associated.Ž¤Map–?ýdefines“two“additional“options“to“document“information“about“its“key“values.‘ úMap“alsoŽ¡defines–?ýits“own“messages“to“distinguish“the“key“value“from“member“value“in“any“operation“whichŽ¡involves‘?ýboth.ŽŸ£×ïhtml:ï html:Ÿïhtml:ï html:¤ k…‘0Â@deftype–ffMap“ŽŸÉ2ïhtml:ï html:ŸPgÅCr½«eate-time‘™™optionsŽŸ‘ýïhtml:ï html:Ÿ }_‘0ÂCREATINGŽ¡‘0-–ff(void)“setKeyType:“aDataType;Ž¡‘0-–ff(void)“setKeySlot:“(int)byteOffset;Ž¡‘0USINGŽ¡‘0-‘0™–getKeyType;Ž¡‘0-–ff(int)“getKeySlot;Ž¡¿(..None–?ýof“these“options“is“currently“implemented.)ŽŸ8äïhtml:ï html:¦ïhtml:ï html:ŸzOÅMap‘™™beha£×viorŽŸ‘ýïhtml:ï html:Ÿ }_‘0Â-–ff(BOOL)“at:“aKey“insert:“anObject;Ž¡‘0-–ff(BOOL)“at:“aKey“insert:“anObject“setIndex:“anIndex;Ž¡¡‘0-–ffat:“aKey“replace:“anObject;Ž¡¿at:insert:‘ úinserts–?ýan“entry“into“a“Map“containing“the“key“and“member“values“given“as“its“arguments.Ž¤It–?ýreturns“true“if“the“key“was“not“previously“contained“in“the“collection.‘ úIf“the“key“wasŽ¡already–?ýpresent,“the“action“of“the“message“depends“on“the“value“in“effect“for“the“DuplicatesOption.Ž¡With–?ýdefault“options,“the“attempt“to“insert“a“duplicate“key“is“simply“rejected“and“false“isŽ¡returned.ŽŸïhtml:ï html:Ÿ k…‘0at:insert:setIndex:‘ úis–?ýsimilar“to“at:insert:,“except“that“the“index“passed“as“theŽ¡‘0final–?ýargument“is“repositioned“to“the“member“just“inserted.‘ úIf“further“operationsŽ¡‘0are–?ýrequired“on“the“entry“in“a“map“that“was“just“inserted,“an“index“provides“fasterŽ¡‘0repeated–?ýaccess“to“this“entry“than“a“message“involving“further“key“comparison,“suchŽ¡‘0as–?ýat:,“would“require.– ú(..“This–?ýmessage“is“not“currently“implemented.)Ž©8äïhtml:ï html:Ÿ2¡‘0at:replace–?ýreplaces“an“existing“member“value“associated“with“a“key“value“by“a“newŽ¡‘0value–?ýgiven“as“its“final“argument.‘ úThe“message“returns“the“member“value“which“wasŽ¡‘0formerly–?ýassociated“with“the“key“value.‘ úThe“message“returns“nil“if“more“than“oneŽ¡‘0member–?ýis“present“with“the“same“key.Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ2¡‘0Â-–ffcreateIndex:“aZone“setKey:“aKey;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹‡ge “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿(..› úThis–?ýmessage“is“not“currently“implemented.˜It“will“eventually“give“a“fast“way“to“createŽŸG®ºâan–?ýindex“already“positioned“at“an“entry“with“a“particular“key“value.)ŽºâŸŸJïhtml:ï html:ŸÊÅMapIndex‘™™beha£×viorŽŸ‘ýïhtml:ï html:Ÿ Ú‘0Â-‘ffgetKey;Ž¤‘0-–ffsetKey:“aKey;Ž¡¿The–?ýgetKey“message“returns“the“key“value“associated“with“the“current“location“of“the“index.Ž¡It–?ýreturns“nil“if“the“index“is“not“currently“positioned“at“a“member.› úThe“setKey:˜messagesŽ¡repositions–?ýthe“index“to“an“entry“having“a“key“value“that“matches“its“argument.‘ úIf“there“isŽ¡more–?ýthan“one“entry“matching“this“key“value,“the“index“is“positioned“to“the“first“entry“thatŽ¡matches.Ž¤ïhtml:ï html:¡ïhtml:ï html:¤‘0Â-–ffget:“(id“*)key;Ž¡‘0-–ffnext:“(id“*)key;Ž¡‘0-–ffprev:“(id“*)key;Ž¡¿These–?ýmessages“are“similar“to“those“defined“by“the“Index“supertype,“except“that“they“combineŽ¡the–?ýreturn“of“a“member“value“with“an“output“value“for“an“associated“key“value.‘ úIn“each“case,Ž¡the–?ýkey“value“is“passed“as“an“(id“*)“output“argument.Ž©8äïhtml:ï html:Ÿïhtml:ï html:Ÿ Ç‘0Â-–ffreplaceKey:“aKey;Ž¡¿(..‘ úThis–?ýmessage“is“not“currently“implemented.)Ž¦ïhtml:ï html:Ÿ Ç‘0replaceKey:‘ úreplaces–?ýa“key“value“with“another“key“value“that“still“compares“equalŽ¡‘0to–?ýa“key“value“already“present.‘ úIt“may“be“used“to“replace“an“allocation“of“one“object,Ž¡‘0already–?ýcontained“in“a“Map,“by“a“different“object“allocation.– úreplaceKey:“returnsŽ¡‘0nil–?ýif“no“existing“key“value“matches“its“key“value“argument;“otherwise“it“returnsŽ¡‘0the–?ýkey“value“which“was“replaced“by“its“argument.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ˆrG “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ ¯ÅString–™™{“character“string“objectŽŸªe¿(..‘ úThis–?ýtype“will“be“more“fully“documented“when“it“is“generalized“beyond“its“current“statusŽŸas–?ýnothing“more“than“an“object“wrapper“for“a“null-terminated“character“array.)ŽŸ Ü»ïhtml:ï html:ŸÇ‘0„¤ŽŽ©G®ïhtml:ï html:ŸÂøÀSynopsisŽŸ âcïhtml:ï html:Ÿ‚`‘0Â//Ž¤Ž‘0//–ffString“--“character“string“objectŽ¡‘0//Ž¡‘0@deftype–ffString“CREATINGŽ¡‘0+–ffcreate:“aZone“setC:“(const“char“*)cstring;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setC:“(const“char“*)cstring;Ž¡‘0USINGŽ¡‘0-–ff(const“char“*)getC;Ž¡‘0-–ff(void)“appendC:“(const“char“*)cstring;Ž¡¡‘0-–ff(int)“getCount;Ž¡‘0-–ff(int)“compare:“aString;Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:ŸÂøÀDescriptionŽŸdÃ¿The–?ýString“object“type“packages“a“null-terminated,“C-format“character“string“into“an“object.Ž¤All–?ýmemory“allocation“needed“to“hold“the“string“value“is“handled“by“the“object.‘ úThis“typeŽ¡currently–?ýdefines“only“the“most“rudimentary“operations“for“initializing“and“appending“C-formatŽ¡character–?ýstrings.‘ úThese“are“sufficient“for“its“current“limited“roles“in“places“that“needŽ¡a–?ýuniformity“between“character“strings“and“other“kinds“of“allocated“objects.ŽŸ—ïhtml:ï html:ŸÇ‘0„¤ŽŽ¤ffïhtml:ï html:ŸN<ÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸÍn‘0Â@deftype–ffString“ŽŸŽ¿...ŽŸïhtml:ï html:¡ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹‰{? “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅCr½«eate-time‘™™optionsŽºâ©‘ýïhtml:ï html:Ÿ Ú‘0ÂCREATINGŽ¤‘0+–ffcreate:“aZone“setC:“(const“char“*)cstring;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setC:“(const“char“*)cstring;Ž¡¿...ŽŸïhtml:ï html:Ÿffïhtml:ï html:ŸG®ÅString‘™™beha£×viorŽ¦ïhtml:ï html:Ÿ Ú‘0Â-–ff(const“char“*)getC;Ž¡‘0-–ff(void)“appendC:“(const“char“*)cstring;Ž¡¡‘0-–ff(int)“getCount;Ž¡‘0-–ff(int)“compare:“aString;Ž¡‘0@endŽ¡¿...ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Š‚¿ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸcUÅOutputStrš½«eam–™™{“str˜eam“of“output“bytesŽŸ¿(..‘ úThis–?ýtype“will“be“more“fully“documented“when“it“is“generalized“beyond“its“current“statusŽŸas–?ýa“placeholder“used“only“to“direct“debuggging“output.)ŽŸ Ü»ïhtml:ï html:ŸÇ‘0„¤ŽŽ©G®ïhtml:ï html:ŸžÀSynopsisŽŸ âcïhtml:ï html:ŸÜ‘0Â//Ž¤`4‘0//–ffOutputStream“--“stream“of“output“bytesŽ¡‘0//Ž¡‘0@deftype–ffOutputStream“CREATINGŽ¡‘0+–ffcreate:“aZone“setFileStream:“(FILE“*)fileStream;Ž¡‘0-–ffsetFileStream:“(FILE“*)fileStream;Ž¡‘0USINGŽ¡‘0-–ff(FILE“*)“getFileStream;Ž¡‘0-–ff(void)“appendC:“(const“char“*)cstring;Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:ŸžÀDescriptionŽŸ¾i¿The–?ýOutputStream“type“currently“supports“only“the“writing“of“a“character“string“to“a“file.Ž¤It–?ýis“a“placeholder“for“more“general“stream“types.‘ úA“stream“is“a“collection“that“supportsŽ¡only–?ýsequential“addition“of“members“(an“output“stream)“or“sequential“removal“of“members“(anŽ¡input‘?ýstream).ŽŸ—ïhtml:ï html:¤ffïhtml:ï html:ŸnþÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ'‘0Â@deftype–ffOutputStream“Ž©`4¿...ŽŸïhtml:ï html:¡ïhtml:ï html:Ÿ§âÅCr½«eate-time‘™™optionsŽŸ‘ýïhtml:ï html:Ÿ r‘0ÂCREATINGŽ¦‘0-–ffsetFileStream:“(FILE“*)fileStream;Ž¦‘0USINGŽ¦‘0-–ff(FILE“*)“getFileStream;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹‹†¾ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿...Žºâ¤ïhtml:ï html:©ffïhtml:ï html:ŸG®ÅSpecial‘™™cr½«eate:‘vÆmessageŽŸ‘ýïhtml:ï html:Ÿ Ú‘0Â+–ffcreate:“aZone“setFileStream:“(FILE“*)fileStream;ŽŸ¿...Ž¡ïhtml:ï html:¦ïhtml:ï html:ŸG®ÅOutputStr½«eam‘™™beha£×viorŽŸ‘ýïhtml:ï html:Ÿ Ú‘0Â-–ff(void)“appendC:“(const“char“*)cstring;Ž¤‘0@endŽ¡¿...ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Œë “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Collections–/Library:‘m™Subclassing“Refer |enceŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤‘0¿Until–?ýthe“collections“library“has“been“fully“implemented,“subclassing“conventionsŽ¡‘0from–?ýcollections“implementation“classes“are“still“in“flux.‘ úIn“general,“these“classesŽ¡‘0will–?ýbe“among“the“most“complex“uses“of“multiple“classes“selected“to“implement“an“independentŽ¡‘0object–?ýtype.‘ ú(See“ïhtml:ï html:library“definition“conventionsïhtml:ï html:Ž¡‘0(../defobj/library.html)Ž¡‘0for–?ýa“summary“of“the“distinction“between“types“and“classes.)‘ úNew“methods“are“beingŽ¡‘0developed–?ýto“simplify“subclassing“from“such“implementations.‘ úIn“the“meantime,“ifŽ¡‘0you–?ýneed“to“use“to“a“collection“within“the“implementation“of“your“own“class,“justŽ¡‘0put–?ýan“instance“variable“in“your“class“and“put“the“collection“in“that,“and“pass“throughŽ¡‘0the–?ýmessages“of“the“collection“you“want“to“have“available“on“your“class“to“this“variable.Ž¡‘0In–?ýmany“if“not“most“cases,“this“is“better“design“anyway,“because“you“control“all“useŽ¡‘0of–?ýthe“underlying“structure.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹‘¦ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Collections–/Library:‘m™Interface“Design“NotesŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¼jÀDesign‘QëObjecti•ÓÅv“esŽŸ^5¿A–?ýcollections“library“is“one“of“the“most“important“foundation“services“for“object-orientedŽ¤programming.‘ úMost–?ýobject-oriented“systems“provide“at“least“the“start“of“a“general-purposeŽ¡collections–?ýlibrary.‘ úThe“GNUSTEP,“project,“for“example,“provides“the“libobject“library“(currentlyŽ¡in–?ýalpha“test“at“ftp://alpha.prep.ai.mit.edu/)“which“includes“a“collections“library“along“withŽ¡other–?ýservices“intended“to“parallel“those“of“the“OpenStep“framework“developed“by“Next.ŽŸ—ïhtml:ï html:© Ç‘0Swarm–?ýhas“implemented“its“own“collection“library“to“meet“the“specialized“needs“ofŽ¡‘0its–?ýagent“simulation“framework.‘ úMajor“objectives“of“the“Swarm“collections“libraryŽ¡‘0include–?ýthe“following:Ž¤8äïhtml:ï html:¦‘0...– ú(..“more–?ýto“come,“obviously)Ž¡ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:¦‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ž˜S “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Collections–/Library:‘m™Implementation“NotesŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:©‘0¿(This–?ýsection“of“documentation“is“not“yet“available.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¡ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ž@ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½ActiÊìvity‘/LibraryŽŸ©^ïhtml:ï html:ŸÇÉ‘0„¤ŽŽŸ ïhtml:ï html:¤ïhtml:ï html:Ÿ‘0ÊDocumentation–and“Implementation“StatusŽŸ ¤Sïhtml:ï html:ŸŽà‘0„¤ŽŽ©G®ïhtml:ï html:Ÿd”ÀOv•ÓÅer“viewŽŸ_¿The–?ýactivity“library“is“responsible“for“scheduling“actions“to“occur“within“a“simulated“world,Ž¡and–?ýfor“making“these“actions“actually“happen“at“the“right“time“in“the“right“order.‘ úIt“providesŽ¡the–?ýfoundation“of“dynamic,“object-oriented“simulation“within“Swarm.ŽŸ—ïhtml:ï html:Ÿ oF‘0Actions–?ýconsist“of“messages“to“objects,“calls“to“functions,“or“groups“of“actions“inŽ¡‘0some–?ýdefined“order.‘ úThe“activity“library“guarantees“that“all“these“actions,“and“theŽ¡‘0state–?ýchanges“they“produce,“occur“at“predictable“points“in“time.‘ úTime“is“definedŽ¡‘0by–?ýthe“relative“order“of“actions,“and“may“also“be“indexed“by“the“discrete“values“ofŽ¡‘0a–?ýworld“clock.ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽ¦ïhtml:ï html:Ÿd”ÀDocumentationŽ¤_¿The–?ýactivity“library“follows“the“Swarm“ïhtml:ï html:library“interface“conventionsïhtml:ï html:Ž¡(defobj/library.html)Ž¤¨*and–?ýhas“the“following“standard“sections“of“documentation:Ž©8äïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:Ÿ oF‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Usage‘?ýGuideïhtml:ï html:Ž¡‘0(activity/guide.html)Ž¦ïhtml:ï html:© oF‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Advanced–?ýUsage“Guideïhtml:ï html:Ž¡‘0(activity/adv.html)ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface‘?ýReferenceïhtml:ï html:Ž¡‘0(activity/ref.html)ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Subclassing‘?ýReferenceïhtml:ï html:Ž¡‘0(activity/subclass.html)ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface–?ýDesign“Notesïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¡ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿(activity/design.html)Žºâ©8äïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Implementation‘?ýNotesïhtml:ï html:Ž¤‘0(activity/impl.html)ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹‘«’ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸçåÀActiÓÅvity–QëLibrary:‘[UDocumentation“and“Implementation“StatusŽŸ^5‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¿The–?ýactivity“library“is“in“process“of“being“converted“to“draw“even“more“of“its“supportŽ¡‘0from–?ýunderlying“types“and“classes“in“the“defobj“and“collections“libraries.‘ úThe“basicŽ¡‘0interface–?ýhas“already“been“changed“to“reflect“this“consolidation,“so“the“programmingŽ¡‘0interface–?ýfor“currently“available“function“is“expected“to“remain“stable.Ž©8äïhtml:ï html:Ÿ Ç‘0The–?ýactivity“library“follows“the“documentation“structure“of“the“Swarm“ïhtml:ï html:library“interfaceŽ¡‘0conventionsïhtml:ï html:Ž¡‘0(../defobj/library.html)Ž¡‘0.‘ úThere–?ýare“placeholders“for“each“section“of“documentation“so“that“all“links“shouldŽ¡‘0at–?ýleast“link“up“with“something,“whether“or“not“there's“anything“there.‘ úThe“InterfaceŽ¡‘0Reference–?ýsection“is“already“fairly“complete,“and“there“is“a“start“toward“a“more“completeŽ¡‘0Usage–?ýGuide“section.‘ úThe“Advanced“Usage“Guide“and“other“sections“will“come“at“a“laterŽ¡‘0time.ŽŸïhtml:ï html:¡‘0Throughout–?ýthe“documentation,“a“parenthesized“comment“that“starts“with“(..‘ úindicatesŽ¡‘0an–?ýeditorial“comment“on“the“current“status“of“implementation“or“documentation.‘ úInŽ¡‘0this–?ýversion,“however,“an“attempt“has“been“made“to“remove“all“discussion“of“futureŽ¡‘0capabilities–?ýand“to“document“instead“only“the“capability“that“is“already“there.Ž¦ïhtml:ï html:Ÿ Ç‘0Source–?ýfor“code“examples“in“the“Usage“Guide“is“included“in“the“text“where“it“occurs.Ž¡‘0Source–?ýconsists“of“fragments“taken“from“example“programs.‘ úThe“example“programs“themselvesŽ¡‘0may–?ýbe“downloaded“from“the“web“pages“and“compiled“on“your“own“system,“using“linksŽ¡‘0provided–?ýfor“that“purpose.– ú(..“currently–?ýthere“are“no“code“examples“in“the“UsageŽ¡‘0Guide,–?ýwhich“so“far“is“only“a“general“overview“of“the“activity“library“..)Ž¦ïhtml:ï html:Ÿ Ç‘0There–?ýis“also“a“directory“of“test“programs“(ïhtml:ï html:GridTurtle“test“programsïhtml:ï html:Ž¡‘0(../grid.html)Ž¡‘0,–?ýcontained“within“the“documentation“release“directory)“that“provides“additional“codeŽ¡‘0examples–?ýof“many“basic“features“of“the“defobj,“collections,“and“activity“libraries.Ž¡‘0These–?ýcode“examples“are“very“rough“and“subject“to“change,“however,“since“their“mainŽ¡‘0use–?ýis“with“each“new“release“of“the“libraries“to“test“various“new“or“existing“features.Ž¡‘0They–?ýare“sometimes“the“only“source,“however,“for“examples“of“some“library“featuresŽ¡‘0that–?ýhave“not“yet“been“used“anywhere“else.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹’®W “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½ActiÊìvity–/Library:‘m™Usage“GuideŽŸ©^ïhtml:ï html:Ÿ‡‘0¿(..› úThis–?ýis“an“overview“of“activity“library“function.˜Code“examples“needed“by“aŽ¤‘0full–?ýusage“guide“will“follow“later.)Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŸdÅRole–™™of“the“actiÛ$vity“library“in“SwarmŽŸc¿The–?ýactivity“library“provides“a“foundation“for“dynamic,“object-oriented“simulation“in“Swarm.Ž¡Swarm–?ýassumes“that“a“user“defines“an“object-oriented“representation“for“the“structure“of“aŽ¡world–?ýto“be“simulated.‘ úOnce“such“a“representation“is“established,“activity“library“componentsŽ¡are–?ýresponsible“for“generating“all“state“changes“and“flow“of“information“within“it.‘ úTheseŽ¡state–?ýchanges“must“be“carefully“controlled“to“ensure“that“they“occur“only“at“appropriate“timesŽ¡and–?ýplaces“in“the“model.‘ úThe“activity“library“provides“mechanisms“to“establish“this“control.ŽŸ Ü»ïhtml:ï html:Ÿ †Ò‘0Once–?ýthe“simulation“of“a“dynamic“model“begins,“everything“that“happens“to“the“modelŽ¡‘0occurs–?ýas“a“direct“result“of“messages“sent“to“world“objects“by“activity“library“components.Ž¡‘0These–?ýcomponents“are“also“represented“by“objects,“since“this“is“the“most“effectiveŽ¡‘0means–?ýfor“their“representation“as“well,“but“their“purpose“is“not“to“represent“theŽ¡‘0current–?ýstate“of“the“simulated“world,“but“rather“to“generate“changes“in“world“objectsŽ¡‘0by–?ýsending“messages“in“a“valid“order.‘ úThe“activity“library“has“two“basic“categoriesŽ¡‘0of–?ýcomponents:‘ úthose“that“represent“messages“to“be“sent,“including“constraints“onŽ¡‘0permissible–?ýorder“for“sending“them,“and“those“that“execute“the“message“sends“theseŽ¡‘0representations–?ýspecify,“making“sure“they“conform“with“all“constraints.Ž¦ïhtml:ï html:Ÿ †Ò‘0All–?ýchanges“to“a“model“occur“as“a“result“of“messages“sent“to“objects“within“it.‘ úTheseŽ¡‘0messages–?ýinvoke“compiled“methods“of“receiving“objects,“which“may“change“local“stateŽ¡‘0or–?ýsend“messages“to“other“objects“to“propagate“effects“as“widely“as“needed.‘ úOnlyŽ¡‘0top-level–?ýfunction“calls“or“message“sends“that“initiate“model“processing“are“the“concernŽ¡‘0of–?ýthe“activity“library.‘ úBecause“the“activity“library“finally“interacts“with“theŽ¡‘0world–?ýmodel“just“by“invoking“its“defined“methods,“the“model“can“prepackage“as“muchŽ¡‘0behavior–?ýas“it“can“in“the“form“of“fast“compiled“methods.‘ úThe“activity“library“justŽ¡‘0triggers–?ýthe“prepackaged“behavior“at“proper“times“under“its“own“explicit,“dynamicallyŽ¡‘0interpreted‘?ýrepresentation.Ž¦ïhtml:ï html:Ÿ †Ò‘0As–?ýconditions“shift“during“execution“of“a“model,“the“model“can“also“examine“and“alterŽ¡‘0the–?ýrepresentation“of“its“future“behavior“contained“in“the“activity“structures“thatŽ¡‘0drive–?ýit.‘ úAny“changes“to“this“future“behavior,“however,“still“occur“only“as“a“resultŽ¡‘0of–?ýsome“currently“executing“action“initiated“by“the“activity“library.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŸdÅActiÛ$vity–™™library“componentsŽŸc¿The–?ýactivity“library“defines“one“set“of“basic“object“types“to“provide“a“very“rich“representationŽ¡of–?ýthe“kinds“of“message“sending“patterns“it“could“generate.‘ úIts“other“major“category“of“objectŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹“»I “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿types–?ýcontrols“and“tracks“a“current“state“of“processing“within“these“representations.ŽºâŸ Ü»ïhtml:ï html:©Å‘0Both–?ýthese“representations“are“more“abstract“than“typical“object“representations,Ž¤‘0since–?ýthey“deal“not“with“any“constant“state“which“can“be“statically“analyzed,“butŽ¡‘0with–?ýshifting“patterns“of“messages“to“be“fired“to“generate“such“state.‘ úWhile“theŽ¡‘0basic–?ýstructure“of“a“Swarm“simulation“is“that“of“a“discrete“event“simulation,“itsŽ¡‘0activity–?ýrepresentation“is“also“more“complicated“than“most“such“systems.ŽŸ8äïhtml:ï html:¦‘0There–?ýare“two“basic“reasons“for“the“potential“complexity“of“a“Swarm“activity“representation.Ž¡‘0One–?ýis“that“Swarm“supports“a“decentralized“representation“of“activity“to“be“generated,Ž¡‘0both–?ýto“reflect“the“nature“of“much“of“the“behavior“that“it“simulates,“and“so“thatŽ¡‘0execution–?ýmay“be“distributed“across“multiple“parallel“processors.‘ úTo“avoid“any“needŽ¡‘0for–?ýsynchronizing“its“decoupled“activities“more“often“than“necessary,“Swarm“enablesŽ¡‘0a–?ýmodel“designer“to“avoid“overspecifying“constraints“on“the“patterns“of“message“sendsŽ¡‘0which–?ýmight“potentially“be“valid.‘ úThe“partial“order“representation“it“adopts“forŽ¡‘0a–?ýdistributed“and“decoupled“plan“of“activity“is“inherently“more“complicated“than“theŽ¡‘0single–?ýcentralized“event“list“adopted“by“many“discrete“event“simulation“systems.ŽŸ8äïhtml:ï html:¦‘0The–?ýother“reason“for“potential“added“complexity“is“that“Swarm's“representation“ofŽ¡‘0intended–?ýactivity“may“be“broken“into“many“separate,“modular“components,“which“canŽ¡‘0be–?ýbound“together“in“various“ways“to“create“larger“components.‘ úThe“Swarm“compositionŽ¡‘0structure,–?ýwhen“fully“implemented,“will“be“fundamentally“as“powerful“as“the“modularŽ¡‘0abstractions–?ýfound“in“most“programming“languages,“with“the“added“complexity“of“controllingŽ¡‘0the–?ýtime“at“which“various“events“occur.Ž©ïhtml:ï html:Ÿ ýô‘0In–?ýspite“of“this“high“potential“complexity,“none“of“these“features“is“needed“for“manyŽ¡‘0simple–?ýmodels,“such“as“those“that“contain“only“a“small“variety“of“basic“behaviors,Ž¡‘0or–?ýwhich“define“all“their“behavior“to“occur“at“regular,“repeating“timesteps.‘ úTheŽ¡‘0Swarm–?ýrepresentation“is“extremely“rich“to“enable“it“to“scale“to“large,“multi-levelŽ¡‘0models–?ýwith“a“variety“of“dependent“behaviors“built“into“the“model,“and“also“to“facilitateŽ¡‘0running–?ýmodels“on“massively“parallel“machines.‘ úMany“of“the“features“which“seem“complex,Ž¡‘0moreover,–?ýare“also“especially“well-suited“to“building“modular“and“reusable“libraryŽ¡‘0components.‘ úIt–?ýis“anticipated“that“many“of“the“more“advanced“features“will“find“theirŽ¡‘0heaviest–?ýusage“in“pre-built“libraries“that“hide“internal“complexity“from“applicationsŽ¡‘0that–?ýuse“them.Ž¦ïhtml:ï html:Ÿ ýô‘0No–?ýmatter“how“complex“the“structures“built“from“them,“all“the“activity“library“componentsŽ¡‘0finally–?ýresult“in“the“direct“execution“of“messages“sends“to“objects“in“a“model.‘ úBecauseŽ¡‘0of–?ýthis“direct“execution,“very“precise“meaning“can“be“defined“for“each“of“them,“inŽ¡‘0terms–?ýof“message“sends“that“can“or“must“occur.‘ úEvery“component“of“a“structure“toŽ¡‘0be–?ýexecuted,“and“every“event“of“its“execution,“can“also“be“accessed“using“the“interfacesŽ¡‘0of–?ýan“object-oriented“representation.‘ úThis“means“that“tools“can“be“built“to“understandŽ¡‘0and–?ýinteract“with“any“components“to“be“executed,“and“also“to“trace“and“debug“activityŽ¡‘0as–?ýit“occurs.‘ úNone“of“these“tools“have“been“built“yet“as“part“of“Swarm,“but“manyŽ¡‘0of–?ýthe“activity“library“interfaces“are“present“to“support“them,“not“because“normalŽ¡‘0use–?ýof“the“library“requires“the“added“components.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹”É| “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅAction–™™plan“componentsŽŸ‘yºâ¿The–?ýfirst“set“of“activity“library“components“represent“messages“to“be“sent“to“objects“in“aŽ¤ºâmodel,–?ýtogether“with“constraints“in“the“order“in“which“they“may“be“sent.‘ úAll“these“componentsŽ¡ºâare–?ýdefined“as“subtypes“of“the“one“generic“type“called“ActionPlan.ŽºâŸ Ü»ïhtml:ï html:© ´¾‘0The–?ýtwo“basic“kinds“of“action“plans“are“a“simple“group“of“actions“to“be“performedŽ¡‘0in–?ýsome“order,“called“an“ActionGroup,“and“a“series“of“actions“to“be“performed“at“discreteŽ¡‘0points–?ýin“time,“called“a“Schedule.‘ úThe“basic“element“of“an“action“plan“is“a“simpleŽ¡‘0object–?ýcalled“an“Action.‘ úAn“action“defines“a“particular“message“to“be“sent“to“anŽ¡‘0object–?ýor“objects.ŽŸ8äïhtml:ï html:¦‘0In–?ýits“representation“of“action“plans,“Swarm“relies“heavily“on“the“dynamic“messageŽ¡‘0sending–?ýcapabilities“of“the“Objective“C“language.‘ úThe“support“of“Objective“C“forŽ¡‘0dynamic–?ýmessage“sends“is“absolutely“crucial“to“Swarm's“implementation“of“generic“activityŽ¡‘0structures.‘ úObjective–?ýC“defines“a“special“kind“of“data“value“called“a“selector,“whichŽ¡‘0identifies–?ýa“message“according“to“its“name.‘ úOne“of“these“selector“values“is“storedŽ¡‘0in–?ýeach“action“of“an“action“plan.‘ úDuring“execution“of“the“plan,“Objective“C“machineryŽ¡‘0performs–?ýthe“actual“message“send“using“its“selector.ŽŸ8äïhtml:ï html:¦‘0Action–?ýplans“are“free-standing“objects“that“may“be“created“directly“by“a“user“program,Ž¡‘0using–?ýa“variety“of“selectable“create-time“options.‘ úOnce“created,“action“plans“mayŽ¡‘0also–?ýrefer“to“each“other,“by“containing“special“kinds“of“actions“to“start“anotherŽ¡‘0action–?ýplan“or“to“perform“all“the“actions“within“it.ŽŸ8äïhtml:ï html:¦‘0Individual–?ýactions“can“be“created“only“as“completely“controlled“components“of“someŽ¡‘0action–?ýplan.‘ úThey“are“created“not“by“a“standard“create“message,“but“by“special“messagesŽ¡‘0(each–?ýcontaining“the“phrase“createAction“in“its“name)“sent“to“an“action“plan“thatŽ¡‘0creates–?ýthe“action“as“part“of“the“action“plan.‘ úIf“the“same“action“is“needed“in“moreŽ¡‘0than–?ýone“plan,“it“has“to“be“created“in“each“plan“where“it“is“needed.‘ úIf“the“entireŽ¡‘0action–?ýplan“is“dropped,“all“its“actions“are“also“automatically“dropped.‘ úSo“the“onlyŽ¡‘0action–?ýplan“components“which“need“to“be“directly“managed“by“an“application“are“theŽ¡‘0action–?ýplans“themselves.ŽŸ8äïhtml:ï html:¦‘0Action–?ýplans“are“relatively“straightforward“components,“because“they“are“entirelyŽ¡‘0passive.‘ úThe–?ýonly“actions“they“ever“contain“are“those“which“an“application“has“createdŽ¡‘0in–?ýthem.‘ úThese“actions“stay“in“them“indefinitely“unless“a“special“option“is“requestedŽ¡‘0to–?ýclean“them“out“as“each“one“is“executed.‘ úBecause“these“plans“are“passive,“read-onlyŽ¡‘0components–?ýto“all“execution“machinery,“if“the“same“pattern“of“actions“needs“to“beŽ¡‘0triggered–?ýat“multiple“points“in“a“model,“it's“perfectly“valid“to“create“one“copy“ofŽ¡‘0the–?ýactions“in“an“action“plan,“and“then“refer“to“the“plan“anywhere“the“actions“mayŽ¡‘0be‘?ýneeded.ŽŸïhtml:ï html:Ÿí¢‘0Even–?ýthough“action“plans“are“passive,“containing“only“what“has“been“placed“in“them,Ž¡‘0there–?ýis“no“requirement“that“their“contents“remain“fixed.‘ úBoth“of“the“action“groupsŽ¡‘0and–?ýschedules“are“implemented“directly“as“collections“of“their“actions.‘ úNew“actionsŽ¡‘0may–?ýbe“added“at“any“time,“and“existing“ones“may“be“dropped“or“moved“from“positionŽ¡‘0to–?ýanother.‘ úThe“contents“of“action“plans“may“be“as“dynamic“as“they“need“to“be“toŽ¡‘0represent–?ýthe“future“actions“needed“in“a“model.‘ úNone“of“these“shifting“contents“hasŽ¡‘0any–?ýeffect“on“the“model“until“actually“processed“during“model“execution.ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹•ÙÞ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:ŸêÀModel–Qëexecution“componentsŽŸ‹Ù¿The–?ýmain“responsibility“of“model“execution“is“just“to“perform“the“actions“specified“by“an“actionŽ¤plan,–?ýin“an“order“of“execution“consistent“with“any“requirements“of“the“plan.‘ úEach“action“planŽ¡may–?ýspecify“as“few“or“as“many“constraints“as“it“likes“over“the“possible“order“in“which“itsŽ¡actions–?ýcould“be“performed.‘ úGiven“these“specifications,“the“execution“objects“are“entirelyŽ¡responsible–?ýfor“selecting“each“action“to“be“performed“and“then“performing“them.ŽŸ—ïhtml:ï html:© ôÀ‘0There–?ýare“two“simple“cases“of“ordering“that“account“for“most“all“usage,“includingŽ¡‘0that–?ýof“the“current“Swarm“demo“programs.‘ úOne“is“to“permit“the“actions“to“be“performedŽ¡‘0in–?ýany“order,“including“concurrent“execution“if“hardware“and“software“support“wereŽ¡‘0available–?ýto“do“this.‘ úThe“other“is“to“require“them“to“be“performed“in“some“specificŽ¡‘0sequence,–?ýone“after“another,“so“that“the“effects“of“one“action“could“depend“on“actionsŽ¡‘0which–?ýpreceded“it.‘ úThis“sequence“could“be“either“fixed“and“predetermined,“or“dynamicallyŽ¡‘0established–?ýeach“time“the“action“plan“is“performed.‘ úIf“a“dynamically“determined“sequenceŽ¡‘0is–?ýneeded,“perhaps“even“selecting“which“actions“are“to“be“performed“at“all,“usersŽ¡‘0can–?ýprovide“custom“subclasses“for“an“action“plan“and“an“execution“object“that“performsŽ¡‘0it.‘ úA–?ýbuiltin“option“is“to“generate“an“entirely“random“sequence“each“time“a“planŽ¡‘0is‘?ýexecuted.ŽŸïhtml:ï html:Ÿ-¤‘0Each–?ýtime“an“action“plan“is“being“processed,“a“special“kind“of“object“called“an“activityŽ¡‘0is–?ýcreated“entirely“automatically“by“the“runtime“processing“machinery.‘ úThese“activityŽ¡‘0objects–?ýimplement“the“internal“machinery“of“a“virtual“processor“which“has“the“abilityŽ¡‘0to–?ýexecute“action“plans.‘ úTo“get“any“activity“started“on“a“model,“a“processor“is“firstŽ¡‘0initialized–?ýto“run“a“single“top-level“plan.‘ úAll“other“activity“during“the“lifetimeŽ¡‘0of–?ýa“model“must“occur“as“a“result“of“actions“initiated“by“this“plan“(which“may“includeŽ¡‘0the–?ýstartup“of“other“plans).ŽŸ8äïhtml:ï html:¦‘0Because–?ýthe“activity“objects“are“internal“to“the“processing“machinery,“an“applicationŽ¡‘0can–?ýusually“just“ignore“their“existence.‘ úThey“come“and“go“dynamically“as“variousŽ¡‘0action–?ýplans“are“started“and“completed,“all“arranged“in“a“stack“or“tree“of“currentŽ¡‘0activities–?ýcontrolled“by“a“single“top-level“processor.‘ úThe“activity“objects“are“potentiallyŽ¡‘0useful,–?ýhowever,“to“obtain“information“about“the“context“in“which“an“action“is“currentlyŽ¡‘0running,–?ýor“to“build“debugging“or“tracing“tools“to“understand“actions“being“performed.ŽŸ8äïhtml:ï html:¦‘0One–?ýof“the“kinds“of“context“information“available“from“an“activity“object“is“the“currentŽ¡‘0time–?ýof“a“clock“value“incremented“as“a“schedule“is“processed.‘ úA“schedule“is“a“kindŽ¡‘0of–?ýaction“plan“in“which“all“actions“occur“at“specific“points“in“time“explicitly“establishedŽ¡‘0within–?ýthe“schedule.‘ úAs“a“schedule“is“executed,“the“activity“object“keeps“a“currentŽ¡‘0time–?ýclock,“which“holds“a“global“time“from“the“start“of“all“model“execution,“regardlessŽ¡‘0of–?ýthe“time“when“the“schedule“itself“was“started.‘ úAn“activity“object“that“processesŽ¡‘0a–?ýschedule“is“called“a“timeline“activity,“because“its“time“continually“increases“fromŽ¡‘0a–?ýglobal“base“time“regardless“of“times“contained“in“the“schedule.ŽŸ8äïhtml:ï html:¦‘0New–?ýactivities“are“created“whenever“an“action“plan“being“processed“contains“an“actionŽ¡‘0to–?ýperform“another“action“plan,“or“to“start“another“action“plan“for“autonomous“execution.Ž¡‘0If–?ýone“action“plan“performs“another,“its“own“processing“is“stopped“until“a“new“activityŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹–ê7 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿processing–?ýthe“other“action“plan“completes.‘ úIf“one“action“plan“starts“another,“theŽ¤‘/ºânew–?ýaction“plan“is“started“as“an“autonomous“activity“controlled“only“by“a“higher-level,Ž¡‘/ºâcontaining‘?ýactivity.Žºâ©8äïhtml:ï html:Ÿ Ç‘0A–?ýSwarm“is“an“activity“that“exists“only“to“control“and“coordinate“other“started“subactivities.Ž¡‘0Unless–?ýthe“subactivities“have“some“special“form“of“explicit“synchronization,“noneŽ¡‘0of–?ýtheir“internal“actions“has“any“required“ordering“relative“to“those“of“other“plansŽ¡‘0except–?ýas“explicitly“established“during“activity“execution.‘ úThe“swarm“can“serve“asŽ¡‘0a–?ýsimple“container“of“started“subactivities“which“only“occasionally“synchronize“forŽ¡‘0messages–?ýthey“send“to“each“other.‘ úThe“swarm“can“be“used“to“hold“collections“of“objectsŽ¡‘0as–?ýwell“as“its“subactivities“as“needed“to“help“them“coordinate“with“one“another.Ž¦ïhtml:ï html:Ÿ Ç‘0One–?ýspecial“form“of“synchronization“within“a“swarm“is“built“into“the“virtual“processingŽ¡‘0machinery.‘ úThis–?ýsynchronization“interleaves“the“actions“that“occur“for“every“successiveŽ¡‘0time–?ývalue“during“processing“of“timeline“subactivities.‘ úThis“merging“of“actions“isŽ¡‘0often–?ýrelied“on“to“interleave“display“and“analysis“processing“with“the“scheduled“actionsŽ¡‘0of–?ýa“base“model.‘ úSince“no“other“mechanisms“for“subactivity“coordination“are“implementedŽ¡‘0in–?ýthe“current“version“of“Swarm,“synchronizing“subschedule“activities“is“the“majorŽ¡‘0current–?ýrole“of“the“Swarm“activity“type.‘ úIn“later“versions“of“Swarm,“a“swarm“willŽ¡‘0also–?ýserve“as“an“important“means“for“organizing“a“large“models“into“clusters“of“moreŽ¡‘0densely–?ýinteracting“components,“and“will“also“provide“a“basis“of“decomposition“forŽ¡‘0parallel‘?ýexecution.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹—úŽ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Acti•Êìvity›/Library:‘m™Adv“anced˜Usage˜GuideŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:©‘0¿(This–?ýsection“of“documentation“is“not“yet“available.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¡ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹˜Ì “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½ActiÊìvity–/Library:‘m™Interface“Refer |enceŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:Ÿö•ÀDependenciesŽŸ˜`¿Following–?ýare“the“other“header“files“imported“by“:ŽŸ—ïhtml:ï html:Ÿïhtml:ï html:Ÿ G‘0Â#import‘ffŽ¤:+¿The–?ýactivity“library“follows“the“Swarm“ïhtml:ï html:library“interface“conventionsïhtml:ï html:Ž¡(../defobj/library.html)Ž¡of–?ýthe“ïhtml:ï html:defobj“libraryïhtml:ï html:Ž¡(../defobj.html)Ž¡.‘ úThe–?ýactivity“library“relies“heavily“on“the“basic“collection“types“defined“in“the“ïhtml:ï html:collectionsŽ©libraryïhtml:ï html:Ž¡(../collections.html)Ž¡,–?ýand“the“collection“interfaces“are“an“integral“part“of“the“interfaces“defined“within“thisŽ¦library.‘ úInitialization–?ýof“the“activity“library“is“done“automatically“by“the“containing“SwarmŽ¦libraries,–?ýand“automatically“initializes“the“collections“and“defobj“libraries“as“well.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿö•ÀList–Qëof“Refer°gence“PÓÅagesŽŸ âcïhtml:ï html:Ÿïhtml:ï html:Ÿµý‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ProcessTypeïhtml:ï html:Ž¡‘0(ProcessType.html)Ž¦ïhtml:ï html:Ÿ G‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ActionTypeïhtml:ï html:Ž¡‘0(ActionType.html)Ž¦ïhtml:ï html:Ÿ G‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿CompoundActionïhtml:ï html:Ž¡‘0(CompoundAction.html)Ž¦ïhtml:ï html:Ÿ G‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ActionGroupïhtml:ï html:Ž¡‘0(ActionGroup.html)Ž¦ïhtml:ï html:Ÿ G‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Scheduleïhtml:ï html:Ž¡‘0(Schedule.html)ŽŸÕSïhtml:ï html:©dØ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SwarmProcessïhtml:ï html:Ž¡‘0(SwarmProcess.html)ŽŸ ÕSïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Action‘?ýTypesïhtml:ï html:Ž¡‘0(Action.html)ŽŸÕSïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Activity‘?ýTypesïhtml:ï html:Ž¡‘0(Activity.html)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹™› “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹š/ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ!ÅPrš½«ocessT‘þï5ype–™™{“specication“of“a“pr˜ocessŽ©‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¼jÀSynopsisŽŸ âcïhtml:ï html:Ÿ{Ò‘0Â//Ž¤‘0//–ffProcessType“--“specification“of“a“processŽ¡‘0//Ž¡‘0@deftype‘ffProcessTypeŽ¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¼jÀDescriptionŽŸ^5¿(..› úFor–?ýnow,“ProcessType“is“just“a“placeholder“for“future“capability.˜..)ŽŸ—ïhtml:ï html:Ÿ Ç‘0ProcessType–?ýwill“eventually“define“support“for“parameterization“of“all“processes.Ž¡‘0A–?ýprocess“is“a“uniquely“identified“course“of“events“that“conforms“to“a“specificationŽ¡‘0of–?ýexternal“and“internal“behavior.ŽŸïhtml:ï html:¡‘0Processes–?ýinclude“both“objects“and“executable“actions.‘ úObjects“change“their“stateŽ¡‘0and–?ýbehavior“based“on“a“sequence“of“externally“initiated“actions.‘ úAn“action,“in“contrast,Ž¡‘0typically–?ýhas“no“external“behavior“other“than“to“be“executed“in“its“entirety“as“aŽ¡‘0unit–?ý(yielding“either“an“observable“result“or“some“change“of“state“in“a“surroundingŽ¡‘0environment).ŽŸÕSïhtml:ï html:Ÿ*‘0Parameterization–?ýwill“be“based“a“uniform“framework“that“defines“all“input“parameters,Ž¡‘0internal–?ýstate“variables,“and/or“final“results,“and“that“provides“for“binding“of“theseŽ¡‘0data–?ýin“a“context“of“execution.‘ úThis“parameterization“framework“is“still“being“established,Ž¡‘0but–?ýProcessType“objects“will“eventually“record“the“specification“of“any“process,“toŽ¡‘0the–?ýextent“that“this“specification“is“defined.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹› “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ·ÅActionT‘þï5ype–™™{“specication“of“an“executable“pr½«ocessŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸphÀSynopsisŽŸ âcïhtml:ï html:Ÿ /Ð‘0Â//Ž¤³þ‘0//–ffActionType“--“specification“of“an“executable“processŽ¡‘0//Ž¡‘0@deftype–ffActionType“-“activateIn:“swarmContext;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸphÀDescriptionŽŸ3¿An–?ýaction“type“is“a“type“of“process“that“may“be“initiated“as“a“unit“of“execution“by“an“externalŽ¤request.‘ úA–?ýtypical“action“has“a“well-defined“duration“determined“by“a“fixed“set“of“actionsŽ¡that–?ýexecute“within“it.‘ úExternally“initiated“interaction“typically“occurs“only“at“the“startŽ¡or–?ýend“of“the“overall“process.‘ úA“typical“action“is“executed“in“its“entirety“once“an“externalŽ¡request–?ýthat“initiates“it“has“occurred.‘ úSome“actions“may“also“have“internal“events“that“cannotŽ¡begin–?ýor“complete“until“other“actions“from“a“containing“environment“have“also“begun“or“completedŽ¡their–?ýexecution.‘ úSuch“ordering“constraints“can“be“defined“either“within“an“action“type“orŽ¡as–?ýpart“of“a“dynamic“context“of“execution.ŽŸ—ïhtml:ï html:© {‘0Executable–?ýactions“include“both“actions“compiled“in“a“host“language“(such“as“C“functionsŽ¡‘0or–?ýObjective“C“messages)“and“compound“actions“built“at“runtime“for“interpretationŽ¡‘0by–?ýthe“Swarm“abstract“machine.ŽŸ8äïhtml:ï html:¦‘0(..› úFor–?ýnow,“the“only“subtype“of“ActionType“is“CompoundAction.˜Types“for“compiledŽ¡‘0actions–?ýsuch“as“functions“and“messages“have“not“been“defined“yet.‘ ú..)Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿû¬ÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸzÞ‘0Â@deftype–ffActionType“ŽŸ³þ¿ActionType–?ýinherits“standard“parameterization“support“from“ProcessType.– ú(..“Currently,‘?ýnoŽ¡such–?ýsupport“is“defined.‘ ú..)Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹œ³ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅActionT‘þï5ype‘™™beha£×viorŽºâŸ‘ýïhtml:ï html:Ÿ Ú‘0Â-–ffactivateIn:“swarmContext;Ž¤¿The–?ýactivateIn:‘ úmessage“is“used“to“initialize“a“process“for“executing“the“actions“of“an“ActionType.Ž¡This–?ýprocess“is“controlled“by“an“object“called“an“Activity.‘ úThe“activateIn“message“initializesŽ¡an–?ýactivity“to“run“under“the“execution“context“passed“as“the“swarmContext“argument,“and“returnŽ¡the–?ýactivity“object“just“created.‘ úIf“the“execution“context“is“nil,“an“activity“is“returnedŽ¡that–?ýallows“complete“execution“control“by“the“caller.‘ úOtherwise,“the“execution“context“mustŽ¡be–?ýeither“an“instance“of“SwarmProcess“or“SwarmActivity.‘ ú(These“objects“are“always“maintainedŽ¡in–?ýone-to-one“association“with“each“other,“either“one“of“the“pair“is“equivalent“to“the“otherŽ¡as–?ýa“swarmContext“argument.)Ž©8äïhtml:ï html:Ÿ Ç‘0If–?ýa“top-level“activity“is“created“(swarmContext“is“nil),“the“created“activity“mayŽ¡‘0be–?ýprocessed“using“activity“processing“commands“such“as“run,“step,“etc.‘ úIf“an“activityŽ¡‘0is–?ýcreated“to“run“under“a“swarm“context,“the“swarm“itself“has“responsibility“for“advancingŽ¡‘0the–?ýsubactivity“according“to“its“requirements“for“synchronization“and“control“amongŽ¡‘0all–?ýits“activities.‘ úActivating“a“plan“for“execution“under“a“swarm“turns“over“controlŽ¡‘0to–?ýthe“swarm“to“execute“the“subactivity“as“a“more-or-less“autonomous“activity.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹%ð “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸJ]ÅCompoundAction–™™{“collection“of“actions“to“be“perf£×ormed“in“some“orderŽ©‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¦ÀSynopsisŽŸ âcïhtml:ï html:Ÿ Ã‘0Â//Ž¤ G<‘0//–ffCompoundAction“--Ž¡‘0//‘32a–ffcollection“of“actions“to“be“performed“in“any“order“consistent“with“aŽ¡‘0//‘32set–ffof“ordering“constraintsŽ¡‘0//Ž¡‘0@deftype–ffCompoundAction“<;ActionType,“Collection>CREATINGŽ¡‘0-–ff(void)“setDefaultOrder:“aSymbol;Ž¡‘0-–ff(void)“setAutoDrop:“(BOOL)autoDrop;Ž¡‘0USINGŽ¡‘0-‘ffgetDefaultOrder;Ž¡‘0-–ff(BOOL)“getAutoDrop;Ž¡‘0@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¦ÀDescriptionŽŸ¥q¿An–?ýcompound“action“is“the“supertype“of“ActionGroup“and“Schedule.‘ úA“compound“action“definesŽ¤an–?ýexecutable“process“that“is“composed“from“the“execution“of“a“set“of“actions“in“some“definedŽ¡order.ŽŸ ^5ïhtml:ï html:Ÿïhtml:ï html:¦‘0„¤ŽŽŸffïhtml:ï html:ŸŽêÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ ‘0Â@deftype–ffCompoundAction“Ž© G<¿CompoundAction–?ýis“not“directly“creatable.› úOne“of“its“subtypes“must“be“created“instead.˜ActionPlanŽ¡inherits–?ýthe“basic“ability“to“be“activated“for“execution“from“ïhtml:ï html:ActionTypeïhtml:ï html:Ž¦(ActionType.html)Ž¦.ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸffïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ž-¨ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅCr½«eate-time‘™™optionsŽºâŸ‘ýïhtml:ï html:Ÿ ™´‘0ÂCREATINGŽ¤‡Ú‘0-–ff(void)“setDefaultOrder:“aSymbol;Ž¡‘0-–ff(void)“setAutoDrop:“(BOOL)autoDrop;Ž¡‘0USINGŽ¡‘0-‘ffgetDefaultOrder;Ž¡‘0-–ff(BOOL)“getAutoDrop;ŽŸ bÌïhtml:ï html:Ÿ ‹t‘0ÊDefaultOrderŽŸ» ¿The–?ýDefaultOrder“option“indicates“the“ordering“to“be“assumed“among“actions“of“the“plan“whenŽ¤no–?ýother“explicit“ordering“has“been“assigned.‘ úBeyond“this“initial“ordering,“additional“orderingŽ¡constraints–?ýcan“be“added“selectively“using“partial“order“specifications“on“individual“actions.Ž¡(..‘ úPartial–?ýorder“order“constraints“are“not“yet“implemented.)ŽŸ lïhtml:ï html:¤ Nö‘0The–?ývalue“for“DefaultOrder“is“a“symbol“that“may“have“one“of“the“following“values:Ž©8äïhtml:ï html:Ÿïhtml:ï html:¡‘0Âextern–ffid“‘ ÌÌConcurrent,“Sequential,“Randomized;ŽŸ‡Ú¿The–?ýConcurrent“value“of“the“DefaultOrder“option“indicates“that“can“actions“be“run“in“any“orderŽ¤(including–?ýat“the“same“time,“if“hardware“and“software“to“do“this“is“available)“without“no“impactŽ¡on–?ýthe“net“outcome“of“the“actions.‘ úThe“claim“that“action“results“are“independent“of“theirŽ¡execution–?ýorder“gives“the“processing“machinery“explicit“leeway“to“execute“them“in“any“orderŽ¡it–?ýchooses.‘ úIn“the“current“implementation“on“a“single,“serial“processor,“actions“are“alwaysŽ¡processed–?ýsequentially“even“if“marked“concurrent,“because“that“is“the“only“way“they“can“be.Ž¡In–?ýfuture“versions,“however,“special“runtime“processing“modes“may“be“defined“even“for“a“serialŽ¡processor,–?ýwhich“would“mix“up“execution“order“just“to“confirm“the“independence“of“model“results.Ž¦ïhtml:ï html:Ÿ Nö‘0The–?ýSequential“value“for“the“DefaultOrder“option“is“the“default.‘ úIt“specifies“thatŽ¡‘0the–?ýactions“must“always“be“executed“in“the“same“order“as“they“occur“in“the“plan.‘ úThisŽ¡‘0order–?ýis“ordinarily“the“same“order“in“which“actions“are“first“created“in“the“plan,Ž¡‘0unless–?ýactions“are“explicitly“added“elsewhere“the“collection“that“underlies“a“plan.Ž¡‘0This–?ýoption“is“always“the“safest“to“assure“predictability“of“results,“but“it“excludesŽ¡‘0the–?ýability“to“run“the“actions“in“parallel.‘ úTo“better“understand“and“document“a“modelŽ¡‘0design,–?ýit“is“worth“annotating“action“plans“with“an“explicit“indication“as“to“whetherŽ¡‘0they–?ýdo“or“do“not“depend“on“a“Sequential“order.Ž¦ïhtml:ï html:Ÿ Nö‘0The–?ýRandomized“value“for“the“DefaultOrder“option“specifies“that“the“model“resultsŽ¡‘0do–?ýdepend“on“execution“order,“but“that“the“order“in“which“the“actions“were“createdŽ¡‘0or–?ýadded“has“no“special“significance.‘ úInstead,“the“method“of“dealing“with“order“dependenceŽ¡‘0is–?ýto“generate“a“random“order“each“time“a“collection“of“same-time“actions“is“processed.Ž¡‘0The–?ýrandom“order“will“be“generated“from“an“random“number“generator“internal“to“theŽ¡‘0processing‘?ýmachinery.Ž¦ïhtml:ï html:¡ïhtml:ï html:Ÿµ\‘0ÊA‘ÿffutoDrÈ¹opŽŸ» ¿The–?ýAutoDrop“option“specifies“that“as“soon“as“any“action“been“processed“by“a“running“activity,Ž¡the–?ýaction“is“removed“from“the“plan“and“dropped“so“that“it“will“never“appear“again.‘ úThis“optionŽ¡is–?ýuseful“for“plans“that“are“created“for“a“one-time“use,“never“to“be“used“again.‘ úThis“optionŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ÿ4› “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿is–?ýespecially“useful“for“a“dynamic“schedule“that“continually“receives“new“actions“to“be“executedŽ¤ºâat–?ýfuture“times,“but“will“never“repeat“actions“that“were“previously“scheduled.‘ úDepending“onŽ¡ºâthe–?ýunderlying“implementation“of“the“schedule,“making“sure“the“old“actions“get“dropped“usingŽ¡ºâAutoDrop–?ýcan“considerably“improve“the“performance“of“the“schedule.ŽºâŸ lïhtml:ï html:Ÿ Ç‘0When–?ýan“option“like“AutoDrop“is“used,“or“whenever“the“contents“of“an“action“plan“undergoŽ¡‘0a–?ýsignificant“amount“of“dynamic“update,“the“action“plan“would“ordinarily“be“intendedŽ¡‘0only–?ýfor“a“single“point“of“use.‘ úIf“AutoDrop“is“specified,“a“restriction“against“multipleŽ¡‘0active–?ýreferences“is“enforced.‘ úAn“error“will“be“raised“if“two“activities“ever“attemptŽ¡‘0to–?ýprocess“a“plan“with“AutoDrop“enabled“at“the“same“time.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ Bç “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸÅActionGr½«oup–™™{“collection“of“actions“under“partial“order“constraintsŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸÌ]ÀSynopsisŽŸ âcïhtml:ï html:Ÿ‹Å‘0Â//Ž¤ó‘0//–ffActionCreating“--“protocol“shared“by“ActionGroup“and“ScheduleŽ¡‘0//Ž¡‘0@deftype‘ffActionCreatingŽ¡‘0-–ffcreateAction:“anActionType;Ž¡¡‘0-–ffcreateActionCall:“(func_t)fptr;Ž¡‘0-–ffcreateActionCall:“(func_t)fptr“:“arg1;Ž¡‘0-–ffcreateActionCall:“(func_t)fptr“:“arg1“:“arg2;Ž¡‘0-–ffcreateActionCall:“(func_t)fptr“:“arg1“:“arg2“:“arg3;Ž¡¡‘0-–ffcreateActionTo:“target“message:“(SEL)aSel;Ž¡‘0-–ffcreateActionTo:“target“message:“(SEL)aSel“:“arg1;Ž¡‘0-–ffcreateActionTo:“target“message:“(SEL)aSel“:“arg1“:“arg2;Ž¡‘0-–ffcreateActionTo:“target“message:“(SEL)aSel“:“arg1“:“arg2“:“arg3;Ž¡¡‘0-–ffcreateActionForEach:“target“message:“(SEL)aSel;Ž¡‘0-–ffcreateActionForEach:“target“message:“(SEL)aSel“:“arg1;Ž¡‘0-–ffcreateActionForEach:“target“message:“(SEL)aSel“:“arg1“:“arg2;Ž¡‘0-–ffcreateActionForEach:“target“message:“(SEL)aSel“:“arg1“:“arg2“:“arg3;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffActionGroup“--Ž¡‘0//‘32a–ffcollection“of“actions“under“total“or“partial“order“constraintsŽ¡‘0//Ž¡‘0@deftype–ffActionGroup“@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸÌ]ÀDescriptionŽŸn(¿An–?ýaction“group“is“an“action“plan“whose“basic“representation“is“a“sequence“of“actions“thatŽ¡have–?ýbeen“created“within“it.‘ úEven“though“a“sequence“is“used“to“represent“the“actions“of“theŽ¡collection,–?ýthis“does“not“necessarily“mean“that“the“execution“machinery“will“process“them“inŽ¡this–?ýorder,“since“the“permissible“order“of“execution“is“still“controlled“by“the“DefaultOrderŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¡H\ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿option–?ýinherited“from“ActionPlan.‘ úThis“initial“order“may“also“be“further“constrained“by“partialŽ¤ºâorder–?ýconstraints“among“the“actions.– ú(..“Partial–?ýorder“constraints“are“currently“unimplemented.)ŽºâŸ—ïhtml:ï html:Ÿffïhtml:ï html:ŸADÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸùZ‘0Â@deftype–ffActionGroup“Ž©2z¿ActionCreating–?ýdefines“the“createAction“messages“for“ActionGroup“just“so“that“this“protocolŽ¡may–?ýbe“shared“with“Schedule,“where“they“provide“a“convenience“interface“for“the“creation“ofŽ¡actions–?ýin“the“schedule“at“time“zero.‘ úThese“messages“will“be“documented“here“in“ActionGroupŽ¡as–?ýif“they“had“been“defined“on“ActionGroup“itself.ŽŸ8äïhtml:ï html:Ÿ ù–‘0An–?ýaction“group“inherits“its“underlying“representation“from“the“ïhtml:ï html:OrderedSetïhtml:ï html:Ž¦‘0(../collections/OrderedSet.html)Ž¦‘0type–?ýof“the“ïhtml:ï html:collectionsïhtml:ï html:Ž¦‘0(../collections.html)Ž¦‘0library.‘ úAll–?ýthe“members“of“the“ordered“set“must“consist“only“of“actions“that“areŽ¡‘0created–?ýby“one“of“the“createAction“messages“defined“on“ActionGroup“itself.‘ úOnce“theŽ¡‘0actions–?ýare“created,“they“may“be“accessed“or“traversed“using“standard“messages“ofŽ¡‘0the–?ýOrderedSet“type.‘ úPartial“orders“on“these“actions“are“also“established“by“inheritedŽ¡‘0messages.– ú(..“Currently,–?ýpartial“orders“are“not“implemented“on“either“collectionsŽ¡‘0or–?ýaction“plans,“but“the“messages“inherited“from“OrderedSet“will“be“the“basic“methodŽ¡‘0for–?ýmaintaining“them“once“implemented.)Ž©8äïhtml:ï html:Ÿffïhtml:ï html:ŸADÅActionGr½«oup‘™™beha£×viorŽŸÖQ¿Actions–?ýare“created“within“the“ActionGroup“using“one“of“the“createAction“messages.‘ úA“createActionTo:Ž¡message–?ýspecifies“that“the“action“to“be“performed“is“defined“by“an“Objective“C“message“selectorŽ¡to–?ýbe“performed“on“a“receiving“object“plus“any“required“arguments.‘ úThe“message“selector“isŽ¡specified–?ýby“the“message:‘ úargument“and“the“receiving“object“is“specified“as“the“first“argument,Ž¡target.ŽŸ Ü»ïhtml:ï html:Ÿ ù–‘0Given–?ýa“variable“aTurtle“already“initialized“to“a“valid“object,“following“is“an“exampleŽ¡‘0of–?ýa“createActionTo“message:Ž¦ïhtml:ï html:Ÿïhtml:ï html:Ÿ ù–‘0Â[createActionTo:–ffaTurtle“message:“M(print)];ŽŸ2z¿M()–?ýis“a“macro“defined“in“defobj.h“which“is“just“a“convenient“shorthand“for“the“Objective“CŽ¡expression–?ý@selector(message-name).‘ úAs“in“any“selector,“the“message“name“must“include“allŽ¡parts–?ýof“the“message“including“colons“and“subsequent“argument“portions.‘ úAn“example“of“a“messageŽ¡with–?ýone“additional“argument“is“the“following:Ž¦ïhtml:ï html:Ÿ ù–‘0Â[createActionTo:–ffaTurtle“message:“$m(move:)“:“(id)10];Ž©2z¿The–?ýcreateAction“messages“declare“all“arguments“of“the“message“to“be“of“object“id“type,“butŽ¡you–?ýare“free“to“cast“other“pointers“and“values“up“to“the“limits“defined“by“the“ïhtml:ï html:global“portabilityŽ¡assumptionsïhtml:ï html:Ž¦(../defobj/globalport.html)Ž¦.‘ úThese–?ýis“not“portable“across“all“machine“architectures,“but“is“expected“to“be“portable“acrossŽ¡the–?ý32-bit“and“64-bit“architectures“on“which“Swarm“will“be“supported.‘ úThe“message“you“sendŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¢PŠ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿must–?ýstill“be“declared“to“receive“the“type“of“argument“you“actually“pass,“before“you“cast“itŽ¤ºâto–?ýthe“id“type.Žºâ©8äïhtml:ï html:Ÿ à¶‘0(..‘ úAlternative–?ýapproaches“to“argument“typing“are“currently“in“development,“but“theseŽ¡‘0will–?ýsupplement“rather“than“replace“the“current“forms“of“createAction“messages.)Ž¦ïhtml:ï html:Ÿ à¶‘0The–?ýcreateAction:‘ úmessage“specifoes“that“processing“of“another“action“type“is“toŽ¡‘0be–?ýperformed“by“the“action.‘ úThe“referenced“action“type“is“performed“in“its“entirety,Ž¡‘0from–?ýstart“to“finish,“as“the“effect“of“the“single“created“action.Ž¦ïhtml:ï html:Ÿ à¶‘0The–?ýcreateActionCall:‘ úmessages“are“similar“to“the“createActionTo“messages,“exceptŽ¡‘0they–?ýspecify“the“action“to“be“performed“as“a“binding“of“a“C“function“to“a“list“ofŽ¡‘0argument–?ývalues.‘ úThe“correct“number“of“arguments“for“the“function“pointer“passedŽ¡‘0as–?ýthe“initial“argument“must“be“supplied.Ž¦ïhtml:ï html:Ÿ à¶‘0The–?ýcreateActionForEach:‘ úmessages“define“a“message“to“be“sent“in“the“same“way“asŽ¡‘0the–?ýcreateActionTo“messages,“but“they“assume“that“the“object“passed“as“the“targetŽ¡‘0argument–?ýis“a“collection“object.‘ úThey“specify“that“each“object“available“from“thatŽ¡‘0collection,–?ýusing“the“standard“messages“of“the“ïhtml:ï html:Collectionïhtml:ï html:Ž¤š‘0(../collections/Collection.html)Ž¡‘0type–?ýin“the“collections“library,“is“to“receive“the“specified“message.Ž¦ïhtml:ï html:Ÿ à¶‘0The–?ýcreateAction:‘ úmessages“specify“that“processing“of“another“action“plan“is“to“beŽ¤‘0performed–?ýby“the“action.‘ úThe“referenced“action“plan“is“performed“in“its“entirety,Ž¡‘0from–?ýstart“to“finish,“as“the“effect“of“the“single“created“action.‘ úIf“parameters“areŽ¡‘0defined–?ýon“the“action“plan,“arguments“for“the“action“can“also“be“given.– ú(..“CurrentlyŽ¡‘0this–?ýis“not“supported,“so“only“the“single“argument“form“of“createAction:‘ úshould“beŽ¡‘0used.)ŽŸÕSïhtml:ï html:ŸDG‘0Each–?ýof“the“createAction“messages“returns“the“action“object“which“it“creates.‘ úEachŽ¡‘0different–?ýkind“of“createAction“message“returns“a“different“type“of“Action“object“withŽ¡‘0a–?ýmatching“name.‘ úThese“Action“objects“provide“access“to“all“the“information“withŽ¡‘0which–?ýthe“Action“was“initialized.‘ úThe“complete“set“of“Action“object“types“is“definedŽ¡‘0below–?ýtogether“with“the“messages“that“may“be“used“to“access“their“contents.– ú(..“TheŽ¡‘0implementation–?ýof“the“Action“objects“is“currently“undergoing“change“as“the“responsibilityŽ¡‘0for–?ýparameter“and“return“value“typing“gets“taken“over“by“ActionType“in“defobj.)Ž¦ïhtml:ï html:Ÿ à¶‘0The–?ýaction“objects“are“an“integral,“controlled“component“of“the“action“plan“in“whichŽ¡‘0they–?ýare“created.‘ úIf“they“are“removed“from“the“action“plan“collection“using“a“removeŽ¡‘0message,–?ýthe“only“collection“in“which“they“may“be“reinserted“is“the“same“collectionŽ¡‘0from–?ýwhich“they“came.‘ úIt“is“permissible,“however,“to“modify“the“base“representationŽ¡‘0sequence–?ýby“removing“from“one“position“and“reinserting“at“another.Ž¦ïhtml:ï html:Ÿ à¶‘0The–?ýcontents“of“the“action“objects“would“ordinarily“be“referenced“only“by“general-purposeŽ¡‘0tools–?ýto“display“or“analyze“an“action“plan“structure.‘ úThe“action“object“id,“however,Ž¡‘0can–?ýalso“be“used“to“establish“additional“ordering“constraints“on“any“of“the“actionsŽ¡‘0in–?ýa“plan.‘ úThese“constraints“supplement“any“initial“order“constraints“establishedŽ¡‘0by–?ýthe“DefaultOrder“option.‘ úConstraints“may“be“established“not“only“within“the“sameŽ¡‘0plan,–?ýbut“between“actions“in“different“plans.– ú(..“Partial–?ýorder“constraints“areŽ¡‘0not–?ýyet“implemented.)Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹£_C “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:ŽŸ‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¤o® “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:ŸAÅSchedule–™™{“collection“of“actions“order½«ed“by“time“vÛ$aluesŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¾ŠÀSynopsisŽŸ âcïhtml:ï html:Ÿ}ò‘0Â//Ž¤ ‘0//–ffSchedule“--“collection“of“actions“ordered“by“time“valuesŽ¡‘0//Ž¡‘0@deftype–ffSchedule“CREATINGŽ¡‘0-–ffcreate:“aZone“setRelativeTime:“(BOOL)relativeTime;Ž¡‘0-–ffcreate:“aZone“setRepeatInterval:“(timeval_t)repeatInterval;Ž¡‘0SETTINGŽ¡‘0-–ff(void)“setConcurrentGroupType:“groupType;Ž¡‘0-–ff(void)“setSingletonGroups:“(BOOL)singletonGroups;Ž¡¡‘0-–ff(void)“setRelativeTime:“(BOOL)relativeTime;Ž¡‘0-–ff(void)“setRepeatInterval:“(timeval_t)repeatInterval;Ž¡‘0USINGŽ¡‘0-‘ffgetConcurrentGroupType;Ž¡‘0-–ff(BOOL)“getSingletonGroups;Ž¡¡‘0-–ff(BOOL)“getRelativeTime;Ž¡‘0-–ff(timeval_t)“getRepeatInterval;Ž¡¡‘0-–ffat:“(timeval_t)tVal“createAction:“anActionType;Ž¡¡‘0-–ffat:“(timeval_t)tVal“createActionCall:“(func_t)fptr;Ž¡‘0-–ffat:“(timeval_t)tVal“createActionCall:“(func_t)fptr:arg1;Ž¡‘0-–ffat:“(timeval_t)tVal“createActionCall:“(func_t)fptr:arg1:arg2;Ž¡‘0-–ffat:“(timeval_t)tVal“createActionCall:“(func_t)fptr:arg1:arg2:arg3;Ž¡¡‘0-–ffat:“(timeval_t)tVal“createActionTo:“target“message:“(SEL)aSel;Ž¡‘0-–ffat:“(timeval_t)tVal“createActionTo:“target“message:“(SEL)aSel:arg1;Ž¡‘0-–ffat:“(timeval_t)tVal“createActionTo:“target“message:“(SEL)aSel:arg1:arg2;Ž¡‘0-Ž©‘0at:–ff(timeval_t)tVal“createActionTo:“target“message:“(SEL)aSel:arg1:arg2:arg3;Ž¡¡‘0-–ffat:“(timeval_t)tVal“createActionForEach:“target“message:“(SEL)aSel;Ž¡‘0-–ffat:“(timeval_t)tVal“createActionForEach:“target“message:“(SEL)aSel:arg1;Ž¡‘0-Ž¦‘0at:–ff(timeval_t)tVal“createActionForEach:“target“message:“(SEL)aSel:arg1:arg2;Ž¡‘0-–ffat:“(timeval_t)tVal“createActionForEach:“target“message:“(SEL)aSel:Ž¡’‰™€arg1:arg2:arg3;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¥q} “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ@endŽŸ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:ŸéüÀDescriptionŽ©‹Ç¿A–?ýschedule“is“compound“action“whose“basic“representation“is“a“sorted“Map“of“actions“that“haveŽ¤been–?ýcreated“within“it.‘ úThe“key“value“associated“with“each“of“these“actions“is“an“unsignedŽ¡integer–?ývalue“for“which“the“typedef“ïhtml:ï html:timeval_tïhtml:ï html:Ž¦is‘?ýsupplied.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿu@ÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿôr‘0Â@deftype–ffSchedule“Ž¤-’¿A–?ýschedule“inherits“its“underlying“representation“from“the“ïhtml:ï html:Mapïhtml:ï html:Ž¡(../collections/Map.html)Ž¡type–?ýof“the“ïhtml:ï html:collectionsïhtml:ï html:Ž¡(../collections.html)Ž¡library.‘ úAll–?ýthe“members“of“the“ordered“set“must“consist“only“of“actions“that“are“createdŽ¤by–?ýone“of“the“createAction“messages“defined“on“Schedule“itself.‘ úOnce“the“actions“are“created,Ž¡they–?ýmay“be“accessed“or“traversed“using“standard“messages“of“the“Map“type.‘ úThe“key“valuesŽ¡of–?ýthis“collection,“however,“must“be“cast“to“and“from“the“id“type“defined“for“key“values“byŽ¡the–?ýMap“type.‘ úPartial“orders“on“these“actions“can“also“established“by“messages“inherited“fromŽ¡Map.– ú(..“Currently,–?ýpartial“orders“are“not“implemented“on“either“collections“or“action“plans,Ž¡but–?ýthe“inherited“messages“will“be“the“basic“method“for“maintaining“them“once“implemented.)Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿu@ÅCr½«eate-time‘™™optionsŽŸî&ïhtml:ï html:Ÿ¥Ò‘0ÊRelati•áIv“eTÈ¹imeŽ©`Å¿The–?ýRelativeTime“option“specifies“that“all“the“times“in“the“schedule“are“relative“to“the“timeŽ¡when–?ýprocessing“of“the“entire“schedule“begins.‘ úOtherwise,“the“times“are“assumed“to“be“absoluteŽ¡times,–?ýwith“their“base“in“the“starting“time“of“the“entire“model.ŽŸ lïhtml:ï html:Ÿ ô®‘0(..‘ úThis–?ýoption“is“currently“supported“only“on“schedules,“not“swarms.)ŽŸ8äïhtml:ï html:Ÿ[‘0ÊRepeatInter•áIv“alŽ¦¿The–?ýRepeatInterval“option“specifies“that“as“soon“as“all“actions“in“the“schedule“have“completed,Ž¡it–?ýis“to“be“rescheduled“at“a“time“computed“as“the“time“at“which“the“schedule“was“last“started,Ž¡plus–?ýthe“value“specified“as“the“RepeatInterval“argument.‘ úThis“option“overrides“the“normalŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¦z' “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿default–?ýthat“times“are“considered“absolute,“as“if“the“RelativeTime“option“had“also“been“specifiedŽ¤ºâat–?ýthe“same“time.‘ úAll“scheduled“times“must“be“less“than“the“specified“repeat“interval,“orŽ¡ºâan–?ýerror“will“be“raised.‘ úThe“RepeatInterval“option“can“continue“to“be“reassigned“to“differentŽ¡ºâvalues–?ýafter“a“schedule“has“been“created,“but“the“interval“value“must“always“be“greater“thanŽ¡ºâthe–?ýscheduled“times“of“any“actions“which“it“contains.Žºâ© lïhtml:ï html:Ÿ ‘0(..› úThis–?ýoption“is“currently“supported“only“on“schedule,“not“swarms.)˜ïhtml:ï html:ïhtml:ï html:ŽŸ8äïhtml:ï html:Ÿ‚v‘0ÊConcurr•È¹entGr“oupT‘ÿ¬ypeŽŸˆ'¿The–?ýConcurrentGroupType“option“is“used“to“control“handling“of“multiple“actions“which“end“upŽ¡being–?ýscheduled“at“the“same“time“value.‘ úAs“far“the“schedule“representation“is“concerned,“theseŽ¡actions–?ýare“assumed“by“default“to“be“concurrently“executable,“and“the“processing“machineryŽ¡is–?ýfree“to“process“them“as“such“if“no“ConcurrentGroupType“option“is“specified.Ž¦ïhtml:ï html:© ‘0If–?ýa“different“interpretation“of“actions“at“the“same“time“step“is“needed,“the“ConcurrentGroupTypeŽ¡‘0option–?ýmay“be“specified.‘ úThe“argument“of“this“option“must“be“an“object“that“whenŽ¡‘0given–?ýa“standard“create:‘ úmessage“will“return“an“object“having“all“the“structure“ofŽ¡‘0a–?ýstandard“ActionGroup“object.‘ úFor“example,“if“you“want“to“specify“that“actions“atŽ¡‘0the–?ýsame“time“step“are“to“be“processed“in“random“order,“you“could“use“the“followingŽ¡‘0procedure:ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ÂconcurrentGroupType–ff=“[ActionGroup“customizeBegin:“aZone];Ž¤Tô‘:ÌÌ[concurrentGroupType–ffsetDefaultOrder:“Random];Ž¡‘:ÌÌconcurrentGroupType–ff=“[concurrentGroupType“customizeEnd];Ž¡¡‘:ÌÌaSchedule–ff=“[Schedule“createBegin:“aZone];Ž¡‘:ÌÌ[aSchedule–ffsetConcurrentGroupType:“concurrentGroupType];Ž¡‘:ÌÌaSchedule–ff=“[aSchedule“createEnd];Ž¡¿Note–?ýthat“instead“of“using“the“normal“createBegin/End“sequence“to“create“an“instance,“the“concurrentGroupTypeŽ¤is–?ýinitialized“using“the“customizeBegin/End“sequence“to“customize“a“type“without“creating“anŽ¡instance.‘ úFor–?ýmore“information,“see“the“defobj“library“documentation.ŽŸ8äïhtml:ï html:¦‘0In–?ýaddition“to“overriding“the“standard“ActionGroup“type,“the“concurrent“group“typeŽ¡‘0may–?ýbe“implemented“by“a“custom“subclass“of“the“ActionGroup“implementation“which“youŽ¡‘0supply–?ýyourself.‘ úA“custom“subclass“is“free“to“implement“custom“rules“for“how“to“combineŽ¡‘0all–?ýthe“actions“which“happen“to“arrive“at“the“same“time“value.‘ úFor“example,“it“couldŽ¡‘0decide–?ýthat“some“actions“are“not“to“be“executed“at“all,“or“it“could“create“entirelyŽ¡‘0new–?ýactions“to“be“executed“instead“of“or“in“addition“to“those“which“were“originallyŽ¡‘0scheduled.– ú(..“Specific–?ýrules“for“writing“a“custom“ActionGroup“subclass“will“beŽ¡‘0documented–?ýat“a“future“time,“but“all“the“apparatus“to“do“so“is“present“today.‘ úA“concurrentŽ¡‘0action–?ýgroup“is“currently“used“to“maintain“the“proper“order“of“execution“among“subswarmsŽ¡‘0of–?ýan“owner“swarm.)ŽŸÕSïhtml:ï html:¡ïhtml:ï html:Ÿ æ‘0ÊSingletonGrÈ¹oupsŽŸˆ'¿The–?ýSingletonGroups“option“indicates“that“an“action“group“should“be“created“for“every“timeŽ¡value–?ýwhich“is“present,“even“when“only“a“single“action“is“present“at“the“time“value.ŽŸ lïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹§… “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿Ordinarily,–?ýa“concurrent“action“group“is“created“to“process“actions“at“the“same“timestepŽ¤‘/ºâonly–?ýif“more“than“one“action“is“scheduled“at“that“timestep.‘ úThe“overhead“of“theseŽ¡‘/ºâaction–?ýgroups“is“relatively“low,“because“it“just“creates“a“single“new“object“to“whichŽ¡‘/ºâactions–?ýare“directly“linked,“but“it“is“still“faster“to“avoid“creating“them“if“onlyŽ¡‘/ºâone–?ýaction“is“present“at“a“timestep.‘ úIf“a“custom“subclass“is“being“provided“however,Ž¡‘/ºâit–?ýmay“need“to“examine“the“actions“at“a“timestep“even“if“there“is“only“one.Žºâ©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:ïhtml:ï html:Ÿffïhtml:ï html:Ÿ\óÅtimeÈ½všÛ$al_t–™™{“type“f£×or“clock“v˜aluesŽŸ¹¿The–?ýfollowing“typedef“is“provided“for“convenience“in“declaring“time“values:ŽŸ Ü»ïhtml:ï html:Ÿïhtml:ï html:Ÿ Üa‘0Âtypedef–ffunsigned‘32timeval_t;‘+30//“type“for“time“valuesŽŸE¿Values–?ýof“this“type“are“used“as“keys“when“inserting“actions“into“a“schedule“at“a“particularŽ¡time,–?ýor“for“querying“the“current“time“value“of“a“swarm“or“schedule“during“its“execution.‘ ú(TheŽ¡shorter–?ýname“time_t“has“already“been“taken“by“one“the“standard“C“libraries.)Ž¦ïhtml:ï html:Ÿ Üa‘0For–?ývery“long“running“models“using“finely“divided“units“of“time,“it“is“quite“possibleŽ¡‘0that–?ýa“32-bit“unsigned“time“value“could“overflow.‘ úSpecial“messages“are“provided“inŽ¡‘0the–?ýexecution“machinery“to“reset“all“times“to“a“different“base“value“if“a“danger“ofŽ¡‘0overflow–?ýexists.‘ úIf“this“machinery“is“exercised,“all“times“of“all“referenced“actionŽ¡‘0plans–?ýare“reset“to“a“different“base“value“in“unison,“which“makes“the“shift“as“transparentŽ¡‘0as–?ýpossible.‘ úSeparate“support“is“also“available“to“declare“time“values“that“are“subunitsŽ¡‘0of–?ýthe“discrete“clock“values“in“a“containing“schedule“or“swarm.– ú(..“Currently,‘?ýallŽ¡‘0this–?ýextended“time“unit“support“is“unsupported,“though“there“is“an“example“of“schedulingŽ¡‘0at–?ýsubunit“times“in“a“ïhtml:ï html:GridTurtleïhtml:ï html:Ž¤E‘0(../grid.html)Ž¡‘0test‘?ýprogram.)Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ\óÅSchedule‘™™beha£×viorŽ¤¹¿The–?ýmessages“to“create“actions“within“a“schedule“are“essentially“the“same“as“those“for“ïhtml:ï html:ActionGroupïhtml:ï html:Ž¡(ActionGroup.html)ŽŸE,–?ýexcept“for“the“presence“of“an“initial“at:‘ úargument“indicating“the“time“at“which“an“actionŽ¤is–?ýto“be“performed.‘ úExcept“for“the“time“associated“with“each“action,“meaning“of“the“createActionŽ¡messages–?ýis“the“same“as“for“ActionGroup.Ž¦ïhtml:ï html:Ÿ Üa‘0When–?ýmultiple“actions“are“all“scheduled“at“the“same“time,“they“are“all“inserted“intoŽ¡‘0a–?ýconcurrent“action“group“created“for“that“time“value.‘ úThe“ïhtml:ï html:ConcurrentGroupTypeïhtml:ï html:ŽŸE‘0option–?ýmay“be“used“to“override“the“default“action“group“for“these“concurrent“actionsŽ¡‘0by–?ýa“custom“user-defined“subclass.– ú(..“Details–?ýof“doing“this“are“not“yet“documented,Ž¡‘0but–?ýthere“are“examples.)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¨“ý “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:¤ ‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹©¡Ê “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ'žÅSwarmPrš½«ocess–™™{“object“that“encapsulates“a“collection“of“pr˜ocessesŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸàçÀSynopsisŽŸ âcïhtml:ï html:Ÿ O‘0Â//Ž¤$}‘0//–ffSwarmProcess“--ŽŸ‘0an–ffobject“that“holds“a“collection“of“concurrent“subprocessesŽ¡‘0//Ž¡‘0@deftype–ffSwarmProcess“CREATINGŽ¡‘0-–ffsetInternalZoneType:“aZoneType;Ž¡‘0-–ff(void)“setSynchronizationType:“aScheduleType;Ž¡¡‘0-–ff(void)“setInternalTimeMultiplier:“(timeval_t)multiplier;Ž¡‘0USINGŽ¡‘0-‘ffgetSynchronizationType;Ž¡‘0-–ff(timeval_t)“getInternalTimeMultiplier;Ž¡¡‘0-‘ffgetInternalZone;Ž¡‘0-‘ffgetActivity;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffActivationOrder“--“default“concurrent“group“type“for“swarmŽ¡‘0//Ž¡‘0@deftype–ffActivationOrder“@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸàçÀDescriptionŽŸ‚²¿A–?ýswarm“is“an“object“created“to“coordinate“the“processing“performed“on“other“action“types.Ž¤Just–?ýlike“any“other“action“type,“a“swarm“may“be“activated“for“running“as“a“subactivity“of“anotherŽ¡swarm.‘ úA–?ýswarm“contains“no“actions“of“its“own,“since“its“only“purpose“is“to“coordinate“theŽ¡processing–?ýof“other“activities.ŽŸ—ïhtml:ï html:Ÿ ë™‘0SwarmProcess–?ýis“the“type“of“an“object“that“can“be“activated“to“run“in“some“context,Ž¡‘0and–?ýwhich“itself“then“defines“a“context“in“which“other“action“plans“can“be“activated.Ž¡‘0Subtypes–?ýof“this“generic“type“can“each“define“a“custom“interface“to“activities“runningŽ¡‘0within–?ýthe“swarm.‘ úThe“generic“swarm“type“defines“only“access“to“an“underlying“activityŽ¡‘0that–?ýkeeps“track“of“the“activated“or“running“subactivities,“along“with“an“option“thatŽ¡‘0may–?ýbe“set“to“a“collection“of“objects“currently“being“processed“by“the“swarm.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ª£Ë “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0¿If–?ýsubactivities“running“within“a“swarm“are“indexed“by“time“(running“either“schedulesŽ¤‘0or–?ýother“swarms),“the“default“coordination“performed“by“the“swarm“is“to“merge“allŽ¡‘0the–?ýdifferent“scheduled“actions“so“that“the“actions“of“one“time“value“are“all“performedŽ¡‘0before–?ýthe“actions“of“any“later“time“value.‘ úIf“the“actions“are“not“indexed“by“time,Ž¡‘0or–?ýif“an“subactivity“has“been“released“from“strict“time“synchronization“with“otherŽ¡‘0subactivities–?ýin“the“swarm,“the“default“coordination“is“limited“to“partial“order“constraintsŽ¡‘0among–?ýthe“action“plans“being“run.– ú(..“Currently–?ýonly“the“merging“of“schedules“andŽ¡‘0subswarms–?ýby“time“values“is“supported.)ŽŸ8äïhtml:ï html:Ÿ ð‘0A–?ýpublic“superclass“called“Swarm“is“supplied“in“the“ïhtml:ï html:objectbase“libraryïhtml:ï html:Ž¤HÔ‘0(../objectbase.html)Ž¡‘0for–?ýuse“in“implementing“custom“swarm“classes.‘ úSuch“a“class“can“override“the“methodŽ©‘0for–?ýthe“activateIn:‘ úmessage“of“ïhtml:ï html:ActionTypeïhtml:ï html:Ž¡‘0(ActionType.html)Ž¡‘0to–?ýautomatically“start“subactivities“to“run“within“a“swarm“when“the“swarm“is“firstŽ¦‘0activated.ŽŸïhtml:ï html:Ÿ‘0„¤ŽŽŸffïhtml:ï html:Ÿ‚ÅInherited‘™™beha£×viorŽŸÜ÷ïhtml:ï html:Ÿ´‘0Â@deftype–ffSwarmProcess“Ž¡¿SwarmProcess–?ýinherits“the“messages“of“both“ïhtml:ï html:ActionTypeïhtml:ï html:Ž¡(ActionType.html)Ž¡and‘?ýïhtml:ï html:Zoneïhtml:ï html:Ž¡(../defobj/Zone.html)Ž¡.‘ úInheritance–?ýof“zone“behavior“means“that“a“swarm“can“be“used“as“the“argument“of“a“create:Ž¦or–?ýcreateBegin:‘ úmessage,“for“creation“of“an“object“within“the“internal“zone“of“a“swarm.Ž¤8äïhtml:ï html:Ÿ ð‘0The–?ýdefault“value“for“the“SynchronizationType“option“is“not“a“generic“action“group,Ž¦‘0but–?ýa“special“predefined“subtype“of“ActionGroup“called“ActivationOrder.‘ úThis“concurrentŽ¦‘0group–?ýtype“guarantees“that“actions“scheduled“to“occur“at“the“same“time“from“differentŽ¦‘0action–?ýplans“running“in“the“same“swarm“are“executed“in“the“same“order“in“which“theŽ¦‘0action–?ýplans“were“first“activated.Ž¡ïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:Ÿ‚ÅCr½«eate-time‘™™optionsŽŸ‘ýïhtml:ï html:Ÿ Z®‘0ÂCREATINGŽ¤HÔ‘0-–ffsetInternalZoneType:“aZoneType;Ž¡‘0-–ff(void)“setSynchronizationType:“aScheduleType;Ž¡‘0-–ff(void)“setInternalTimeMultiplier:“(timeval_t)multiplier;Ž¡‘0USINGŽ¡‘0-‘ffgetSynchronizationType;Ž¡‘0-–ff(timeval_t)“getInternalTimeMultiplier;ŽŸ bÌïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹«¬9 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÊInterÑónalZoneT‘ÿ¬ypeŽ©33ºâ¿The–?ýInternalZoneType“option“sets“the“type“of“zone“which“is“created“by“the“swarm“to“hold“objectsŽ¤ºâcreated–?ýwithin“the“swarm.‘ úIf“set“to“nil,“no“internal“zone“is“created“within“the“swarm,“andŽ¡ºâall–?ýuse“of“the“swarm“as“if“it“were“a“zone“raises“an“error.‘ úThe“default“of“this“option“is“standardŽ¡ºâZone›?ýtype.– ú(..“Since˜there˜is˜no˜other˜Zone˜type˜yet,˜there's˜no˜reason˜to˜set˜this˜optionŽ¡ºâyet–?ýexcept“to“turn“off“the“internal“zone.‘ ú..)ŽºâŸ lïhtml:ï html:¡ïhtml:ï html:Ÿ-‚‘0ÊSynchrÈ¹onizationT‘ÿ¬ypeŽ¦¿Synchronization–?ýtype“sets“the“type“of“schedule“which“is“used“internally“by“the“swarm“to“synchronizeŽ¡subschedules.‘ úIts–?ýdefault“is“a“schedule“with“a“concurrent“group“of“ActivationOrder.ŽŸ lïhtml:ï html:¡ïhtml:ï html:Ÿ-‚‘0ÊInterÑónalTÈ¹imeMultiplierŽ¦¿(..‘ úThis–?ýoption“will“be“used“in“the“future“to“support“an“internal“time“unit“within“the“swarmŽ¡that–?ýcan“be“more“fine-grained“than“the“context“in“which“the“swarm“is“included.‘ ú..)ŽŸ lïhtml:ï html:ŸÇ‘0„¤ŽŽŸffïhtml:ï html:ŸG®ÅSwarmPr½«ocess‘™™beha£×viorŽŸÜ÷ïhtml:ï html:ŸÆà‘0Â-‘ffgetInternalZone;Ž¡‘0-‘ffgetActivity;Ž¡¿getInternalZone–?ýreturns“a“Zone“object“that“is“used“by“the“swarm“to“hold“its“internal“objects.Ž¡Even–?ýthough“the“swarm“itself“inherits“from“Zone“and“can“be“used“as“a“Zone“for“nearly“all“purposes,Ž¡this–?ýmessage“is“also“provided“so“that“the“zone“itself“can“be“obtained“independent“of“all“zoneŽ¡behavior.ŽŸïhtml:ï html:¡‘0getActivity–?ýreturns“the“activity“which“is“currently“running“of“subactivities“withinŽ¡‘0the–?ýswarm.› úThis“activity“is“the“same“as“the“value“returned“by“activateIn:˜when“theŽ¡‘0swarm–?ýwas“first“activated.‘ úIt“returns“nil“if“the“swarm“has“not“yet“been“activated.Ž©8äïhtml:ï html:Ÿ Ç‘0Unlike–?ýother“action“types,“swarms“and“swarm“activities“always“exist“in“a“one-to-oneŽ¡‘0relationship,–?ýprovided“that“the“swarm“has“been“activated.‘ úThis“restriction“to“a“singleŽ¡‘0activity–?ýenables“the“swarm“to“do“double-duty“as“a“custom“object“that“provides“itsŽ¡‘0own–?ýinterface“to“the“activities“running“within“the“swarm.Ž¦ïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¬¸g “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸžâÀNameŽŸªóïhtml:ï html:Ÿ¡ƒÅAction–™™{“element“of“a“compound“actionŽ©‘0„¤ŽŽŸG®ïhtml:ï html:ŸZÌÀSynopsisŽŸ âcïhtml:ï html:Ÿ 4‘0Â//Ž¤žb‘0//–ffAction“--“messages“shared“by“ActionCall,“ActionTo,“and“ActionForEachŽ¡‘0//Ž¡‘0@deftype–ffAction“-“(int)“getNArgs;Ž¡‘0-–ff(void)“setArg1:“arg1;Ž¡‘0-‘ffgetArg1;Ž¡‘0-–ff(void)“setArg2:“arg2;Ž¡‘0-‘ffgetArg2;Ž¡‘0-–ff(void)“setArg3:“arg3;Ž¡‘0-‘ffgetArg3;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffActionCall“--“an“action“defined“by“calling“a“C“functionŽ¡‘0//Ž¡‘0@deftype–ffActionCall“-“(void)“setFunctionPointer:“(func_t)fptr;Ž¡‘0-–ff(func_t)“getFunctionPointer;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffActionTo“--“an“action“defined“by“sending“an“Objective“C“messageŽ¡‘0//Ž¡‘0@deftype–ffActionTo“-“(void)“setTarget:“target;Ž¡‘0-‘ffgetTarget;Ž¡‘0-–ff(void)“setMessageSelector:“(SEL)aSel;Ž¡‘0-–ff(SEL)“getMessageSelector;Ž¡‘0@endŽ¡¡‘0//Ž¡‘0//–ffActionForEach“--ŽŸ‘0an–ffaction“defined“by“sending“to“every“member“of“a“collectionŽ¡‘0//Ž¡‘0@deftype–ffActionForEach“@endŽ¦‘0„¤ŽŽŸG®ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ã– “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÑçåºâÀDescriptionŽŸ^5ºâ¿Action–?ýis“a“common“supertype“of“all“action“types“which“may“be“created“within“an“action“plan.Ž¤ºâEach–?ýaction“is“always“controlled“by“a“single“action“plan“to“which“it“belongs.‘ úThis“actionŽ¡ºâplan–?ýis“referred“to“as“its“owner.‘ úGiven“the“action“object,“its“owner“plan“may“be“obtainedŽ¡ºâusing–?ýthe“inherited“getOwner“message.ŽºâŸ—ïhtml:ï html:© Ç‘0Actions–?ýare“allocated“in“the“same“zone“as“their“owner“plan,“and“may“be“created“onlyŽ¡‘0using–?ýone“of“the“createAction“messages“on“an“ActionGroup“or“Schedule.‘ úEach“of“theseŽ¡‘0messages–?ýreturns“the“action“that“was“created“as“its“return“value.‘ úActions“in“an“actionŽ¡‘0plan–?ýmay“also“be“obtained“by“processing“the“plan“using“any“of“its“messages“inheritedŽ¡‘0from–?ýits“underlying“collection.‘ úActions“may“also“be“removed“from“an“action“plan“usingŽ¡‘0a–?ýremove“message“on“the“underlying“collection.ŽŸ8äïhtml:ï html:¦‘0(..– úNote:“currently,–?ýan“action“cannot“be“removed“while“it“is“currently“being“executed.Ž¡‘0This–?ýmeans“that“the“function“or“message“called“by“an“action“cannot“itself“remove“thatŽ¡‘0same–?ýaction“from“its“action“plan.‘ úThis“restriction“will“be“removed“in“the“future.)Ž¡‘0No–?ýmatter“what“the“type“of“action,“the“default“ordering“constraints“established“byŽ¡‘0its–?ýmembership“in“an“owning“plan“may“be“supplemented“by“explicit“specification.‘ úTheseŽ¡‘0specifications–?ýare“made“directly“between“actions“in“the“same“plan,“or“between“actionsŽ¡‘0in–?ýdifferent“plans“if“they“are“suitably“qualified.‘ úGiven“any“action“belonging“toŽ¡‘0any–?ýplan,“the“set“of“specific“explicit“ordering“constraints“in“which“it“participatesŽ¡‘0may–?ýbe“obtained“by“one“of“the“messages“getSuccessors,“getPredecessors,“getCostarts,Ž¡‘0and–?ýCoends“inherited“from“the“ïhtml:ï html:KeyedCollectionïhtml:ï html:Ž¡‘0(../collections/KeyedCltn.html)Ž¡‘0type.ŽŸ8äïhtml:ï html:¦‘0Separate–?ýsubtypes“of“Action“are“defined“for“each“of“the“various“forms“of“createActionŽ¡‘0messages–?ýthat“create“them.‘ úThe“current“representation“of“these“actions“will“be“undergoingŽ¡‘0change–?ýas“support“for“their“parameter“and“return“types“is“migrated“into“more“basicŽ¡‘0support–?ýfrom“the“ïhtml:ï html:defobjïhtml:ï html:Ž¡‘0(../defobj.html)Ž¡‘0library.‘ úEach–?ýaction“type“provides“messages“to“retrieve“and“set“the“values“of“allŽ¡‘0argument–?ývalues“bound“into“the“action.‘ úThese“capabilities“will“remain,“but“differentŽ¡‘0messages–?ýwill“eventually“be“supported.‘ úThis“documentation“will“be“completed“onceŽ¡‘0the–?ýmessages“supported“on“Action“types“are“finalized.Ž©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Roger–?ýBurkhart“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:rmb@santafe.edu)Ž¦ïhtml:ï html:Ÿ Ç‘0¿Last–?ýmodified:‘ ú1997-12-19“(mgd)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹®É[ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½ActiÊìvity‘/T‘þw.ypesŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:ŸÊÀContentsŽŸkÚ¿The–?ýfollowing“object“types“are“documented“below:ŽŸ—ïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:¤ ÔÁ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Activityïhtml:ï html:Ž©8äïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿GroupActivityïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ForEachActivityïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ScheduleActivityïhtml:ï html:Ž¦ïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SwarmActivityïhtml:ï html:ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:ïhtml:ï html:ŸG®ïhtml:ï html:ŸÊÀNameŽŸªóïhtml:ï html:ŸÆÅActiÛ$vity–™™{“state“of“pr½«ocessing“within“an“action“planŽŸ5Ôïhtml:ï html:ŸÛéÀSynopsisŽŸ âcïhtml:ï html:Ÿ‰w‘0Â//Ž¤ ¥‘0//–ffActivity“--“state“of“processing“within“an“action“planŽ¡‘0//Ž¡‘0@deftype–ffActivity“-“run;Ž¡‘0-‘Pÿústop;Ž¡‘0-–ff(void)“terminate;Ž¡¡‘0-‘ffnext;Ž¡‘0-‘ffstep;Ž¡‘0-‘ffstepEntry;Ž¡‘0-‘ffstepExit;Ž¡¡‘0-‘ffgetStatus;Ž¡‘0-‘ffgetHoldType;Ž¡¡‘0-‘ffgetAction;Ž¡‘0-‘ffgetActionType;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¯ÖH “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤dŒ‘/ºâÂ-–ff(void)“setOwnerActivity:“ownerActivity;Ž¡‘/ºâ-‘ffgetOwnerActivity;Ž¡¡‘/ºâ-‘ffgetSubactivities;Ž¡¡‘/ºâ-‘ffgetControllingActivity;Ž¡‘/ºâ-‘ffgetTopLevelActivity;Ž¡‘/ºâ-‘ffgetSwarmActivity;Ž¡‘/ºâ-‘ffgetScheduleActivity;Ž¡¡‘/ºâ-–ffsetSerialMode:“(BOOL)serialMode;Ž¡‘/ºâ-–ff(BOOL)“getSerialMode;Ž¡¡‘/ºâ-–ffgetCurrentSubactivity;‘ ÌÌ//“serial“mode“onlyŽ¡‘/ºâ@endŽŸ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:Ÿ öÀDescriptionŽŸÂÁ¿A–?ýobject“of“type“Activity“implements“the“processing“of“actions“within“an“action“plan.‘ úEachŽ¤subtype–?ýof“action“plan“has“a“corresponding“subtype“of“Activity“that“implements“processing“ofŽ¡its–?ýrespective“type“of“plan.ŽŸ—ïhtml:ï html:© +¨‘0The–?ýActivity“types“are“part“of“the“virtual“processing“machinery“of“an“action“planŽ¡‘0interpreter.‘ úAll–?ýthe“important“elements“of“this“machinery,“including“their“currentŽ¡‘0state–?ýof“processing,“are“exposed“to“aid“in“development“of“general-purpose“tools“suchŽ¡‘0as–?ýdebuggers.‘ úExcept“for“applications“that“need“to“create“and“run“their“own“reflectiveŽ¡‘0activities,–?ýdirect“use“of“activity“types“by“a“modeling“application“should“be“rare.ŽŸ8äïhtml:ï html:¦‘0An–?ýnew“activity“object“is“created“by“each“activateIn:‘ úmessage“sent“to“an“action“type.Ž¡‘0activateIn:‘ úinitializes–?ýa“new“activity“object“and“prepares“it“for“processing,“butŽ¡‘0does–?ýnot“itself“execute“any“actions.‘ úSubsequent“messages,“such“as“run,“must“be“usedŽ¡‘0to–?ýinitiate“processing“within“an“activity.‘ úIf“an“activity“is“activated“to“run“underŽ¡‘0a–?ýswarm“context,“the“owning“swarm“itself“controls“all“processing“within“the“subactivity.ŽŸ8äïhtml:ï html:¦‘0An–?ýActivity“type“holds“a“tree“of“currently“running,“or“a“potentially“runnable,“subactivities.Ž¡‘0Each–?ýactivity“object“represents“a“state“of“processing“within“a“single“action“plan.Ž¡‘0The–?ýstructure“is“a“tree“because“multiple“activities“could“be“running“or“eligible“toŽ¡‘0run–?ýat“the“same“time.‘ úThis“occurs“whenever“two“activities“are“specified“as“concurrent,Ž¡‘0either–?ýbecause“are“being“performed“by“concurrent“actions“in“some“other“plan,“or“becauseŽ¡‘0they–?ýwere“started“for“autonomous“execution“under“the“same“swarm.‘ úWhen“parallel“processingŽ¡‘0machinery–?ýis“present,“each“activity“could“also“be“advancing“its“own“state“independentŽ¡‘0of–?ýthose“of“any“other“activity.ŽŸ8äïhtml:ï html:¦‘0The–?ýcurrent“implementation“supports“only“a“single“serial“processor.‘ úUnder“serialŽ¡‘0execution,–?ýonly“one“activity“may“be“active“at“one“time.‘ úThis“means“that“the“currentŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹°ÝÕ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿state–?ýof“processing“may“be“represented“by“a“single“stack“of“current“activities“thatŽ¤‘/ºâtraces–?ýa“path“to“a“single“leaf“of“the“runnable“activity“tree.‘ úWhen“running“in“serialŽ¡‘/ºâmode,–?ýmessages“are“available“to“obtain“the“currently“running“leaf“activity“or“usefulŽ¡‘/ºâcontext–?ýinformation“such“as“the“current“time“available“from“it.ŽºâŸïhtml:ï html:Ÿ‘0„¤ŽŽŸffïhtml:ï html:Ÿ\ÅActiÛ$vity‘™™beha£×viorŽ©ë…¿(..‘ úSpecific–?ýmessages“for“activity“objects“are“still“subject“to“change“as“some“of“their“underlyingŽ¡support–?ýmigrates“to“the“ïhtml:ï html:defobjïhtml:ï html:Ž¦(../defobj.html)Ž©G®library.‘ úFor–?ýnow,“this“section“will“document“just“the“basic“messages“to“start“and“controlŽ¡processing–?ýwithin“an“activity.)ŽŸ8äïhtml:ï html:Ÿ Ê‘0Â-‘ffrun;Ž¦‘0-‘Pÿústop;Ž¦‘0-–ff(void)“terminate;Ž¦¿The–?ýrun“message“continue“processing“of“an“activity“from“any“state“in“which“its“execution“hasŽ¡been–?ýsuspended.› úAn“error“is“raised“if“the“activity“is“already“running.˜run“returns“eitherŽ¡a–?ýStopped“or“Completed“status“that“the“activity“has“when“it“is“no“longer“eligible“to“be“runŽ¡further.ŽŸïhtml:ï html:¦‘0The–?ýstop“message“causes“the“a“currently“running“tree“of“activities“to“stop“furtherŽ¡‘0processing–?ýand“return“a“Stopped“status.‘ úterminate“also“stops“a“running“tree“of“activities,Ž¡‘0but–?ýsets“all“activities“within“the“tree“to“a“status“of“Completed“whenever“the“treeŽ¡‘0is–?ýnext“run.‘ úterminate“may“be“used“on“either“a“running“or“stopped“tree“of“activities.Ž¡‘0It–?ýis“the“standard“way“to“terminate“schedule“that“is“endlessly“repeating“under“theŽ¡‘0RepeatInterval‘?ýoption.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:Ÿ Ê‘0Â-‘ffnext;Ž¦‘0-‘ffstep;Ž¦‘0-‘ffstepEntry;Ž¦‘0-‘ffstepExit;Ž¦¿The–?ýnext“executes“actions“within“a“single“compound“action“while“skipping“over“all“processingŽ¡of–?ýany“complete“action“plans“executed“by“those“actions.‘ úThe“step“message“executes“a“singleŽ¡action–?ýwithin“a“tree“of“activities.‘ úThe“stepEntry“message“executes“multiple“actions“withinŽ¡a–?ýsingle“currently“runnable“activity,“but“stops“the“activity“when“a“new“level“of“action“planŽ¡has–?ýjust“been“started“within“the“tree“of“activities.‘ ústepExit“executes“multiple“actions“inŽ¡the–?ýsame“action“plan“until“the“activity“for“that“action“plan“has“completed,“or“cannot“otherwiseŽ¡be–?ýrun“further.– ú(..“Currently,–?ýstepEntry“and“stepExit“are“unimplemented.)ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:Ÿ Ê‘0Â-‘ffgetStatus;Ž¦‘0-‘ffgetHoldType;Ž¦¿The–?ýgetStatus“message“returns“one“of“the“following“codes“for“the“current“run“status“of“a“particularŽ¡activity:ŽŸ8äïhtml:ï html:Ÿ Ê‘0Âextern–ffid“‘ ÌÌInitialized,“Running,“Stopped,“Holding,ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹±é8 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘ETzÂReleased,–ffTerminated,“Completed;ŽŸ )iºâ¿The–?ýgetHoldType“returns“a“code“for“the“particular“hold“constraint“under“which“an“activity“isŽ¤ºâcurrently–?ýholding.› úIt“returns“nil“if“the“basic“status“of“the“activity“is“not“Holding.˜(..Ž¡ºâCurrently–?ýno“hold“constraints“other“than“merging“within“a“swarm“are“supported,“and“this“messageŽ¡ºâalways–?ýreturns“nil.)ŽºâŸ8äïhtml:ï html:Ÿïhtml:ï html:© ð…‘0Âextern–ffid“‘ ÌÌHoldStart,“HoldEnd;ŽŸ‘0„¤ŽŽŸffïhtml:ï html:ŸqÅActiÛ$vity–™™context“macr½«osŽŸÍ@¿The–?ýcurrent“running“activity“is“always“available“for“reference“within“any“action“running“withinŽ¡the›?ýactivity.– ú(..“Currently,˜the˜getCurrentActivity()˜macro˜raises˜an˜error,˜but˜the˜otherŽ¡macros–?ýwork“as“long“as“there“is“a“currently“running“activity.– ú..)“The–?ýfollowing“macros“provideŽ¡access–?ýto“various“information“available“from“the“current“running“activity“and“its“owner“activities:ŽŸ Ü»ïhtml:ï html:¦‘0Â#define‘ ÌÌgetCurrentActivity()Ž¤ )i‘0#define‘ ÌÌgetCurrentAction()Ž¡‘0#define‘ ÌÌgetCurrentTime()Ž¡‘0#define‘ ÌÌgetCurrentScheduleActivity()Ž¡‘0#define‘ ÌÌgetCurrentSchedule()Ž¡‘0#define‘ ÌÌgetCurrentSwarmActivity()Ž¡‘0#define‘ ÌÌgetCurrentSwarm()Ž¡‘0#define‘ ÌÌgetCurrentSwarmActivity()Ž¡‘0#define‘ ÌÌgetTopLevelActivity()ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:©åÓÀActiÓÅvity‘QësubtypesŽŸ âcïhtml:ï html:Ÿ ¥;‘0¿(..› úOnly–?ýa“synopsis“of“Activity“subtypes“is“provided“here“for“now.˜Note,“howeverŽ¤‘0that–?ýaccess“to“a“current“time“is“available“from“a“schedule“or“swarm“activity,“alongŽ¡‘0with–?ýthe“ability“to“run“a“schedule“until“a“particular“time“value“is“first“reached.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸ ïhtml:ï html:ïhtml:ï html:ŸG®ïhtml:ï html:¦ÀNameŽŸªóïhtml:ï html:Ÿ,ŠÅGrš½«oupActiÛ$vity–™™{“state“of“pr˜ocessing“within“an“ActionGr˜oupŽŸ5Ôïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹²õ© “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÑçåºâÀSynopsisŽºâ© âcïhtml:ï html:Ÿ÷2‘0Â//Ž¤{`‘0//–ffGroupActivity“--“state“of“processing“within“an“ActionGroupŽ¡‘0//Ž¡‘0@deftype–ffGroupActivity“@endŽŸ‘0„¤ŽŽŸ ïhtml:ï html:ïhtml:ï html:ŸG®ïhtml:ï html:Ÿ7ÊÀNameŽŸªóïhtml:ï html:Ÿ~ÅFš£×orEachActiÛ$vity–™™{“state“of“pr½«ocessing“within“an“F˜orEach“actionŽŸ5Ôïhtml:ï html:ŸI¤ÀSynopsisŽ¦ïhtml:ï html:Ÿ÷2‘0Â//Ž¡‘0//–ffForEachActivity“--“state“of“execution“within“a“ForEach“actionŽ¡‘0//Ž¡‘0@deftype–ffForEachActivity“Ž¡‘0-‘ffgetCurrentMember;Ž¡‘0@endŽŸ‘0„¤ŽŽŸ ïhtml:ï html:ïhtml:ï html:ŸG®ïhtml:ï html:Ÿ7ÊÀNameŽŸªóïhtml:ï html:Ÿ~ÅScheduleActiÛ$vity–™™{“state“of“execution“within“a“ScheduleŽŸ5Ôïhtml:ï html:ŸI¤ÀSynopsisŽ¦ïhtml:ï html:Ÿ÷2‘0Â//Ž¡‘0//–ffScheduleActivity“--“state“of“execution“within“a“ScheduleŽ¡‘0//Ž¡‘0@deftype–ffScheduleActivity“Ž¡‘0-‘ff(timeval_t)‘32getCurrentTime;Ž¡¡‘0-–ffstepUntil:“(timeval_t)tVal;‘ ÌÌ//“unimplementedŽ¡‘0@endŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹³þÆ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâ© ïhtml:ï html:ïhtml:ï html:ŸG®ïhtml:ï html:Ÿ¼jÀNameŽŸªóïhtml:ï html:Ÿ!ÅSwarmActišÛ$vity–™™{“a“collection“of“started“subacti˜vitiesŽŸ5Ôïhtml:ï html:ŸÎDÀSynopsisŽŸ âcïhtml:ï html:Ÿ{Ò‘0Â//Ž¤‘0//–ffSwarmActivity“--“a“collection“of“started“subactivitiesŽ¡‘0//Ž¡‘0@deftype–ffSwarmActivity“Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹´ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½ActiÊìvity–/Library:‘m™Subclassing“Refer |enceŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤‘0¿Subclassing–?ýis“supported“by“the“activity“library“as“an“integral“technique“for“extendingŽ¡‘0the–?ýframework“it“implements.‘ úThere“are“two“specific“places“where“subclassing“is“expectedŽ¡‘0as–?ýthe“normal“technique“of“extension:‘ údefinition“of“concurrent“action“groups,“andŽ¡‘0definition–?ýof“customized“swarm“objects.‘ úConcurrent“action“groups“are“not“yet“fullyŽ¡‘0documented–?ýbecause“their“full“interface“is“still“being“finalized.‘ úSwarm“subclassesŽ¡‘0should–?ýinherit“from“the“Swarm“superclass“defined“in“the“ïhtml:ï html:objectbaseïhtml:ï html:Ž¡‘0(../objectbase.html)Ž¡‘0library;–?ýthe“activity“library“provides“the“underlying“support“packaged“by“this“superclass.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹µB “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½ActiÊìvity–/Library:‘m™Interface“Design“NotesŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:©‘0¿(This–?ýsection“of“documentation“is“not“yet“available.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¡ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¶ ¿ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâŸ¼jïhtml:ï html:Ÿâ½ActiÊìvity–/Library:‘m™Implementation“NotesŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:©‘0¿(This–?ýsection“of“documentation“is“not“yet“available.)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¡ïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¦‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last–?ýmodified:‘ ú1998-01-08“(mgd)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹· “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Objectbase‘/LibraryŽŸq'‘0„¤ŽŽŸïhtml:ï html:ŸœU‘0ÊDocumentation–and“Implementation“StatusŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ)Â’Úqï>PSfile="eps/bomb.eps" llx=290 lly=365 urx=321 ury=396 rwi=310 ŽŽŸòYÀCompatibilityŽŸ âcïhtml:ï html:¤ïhtml:ï html:Ÿ±Á‘0ïcolor push BlackÁlï color popŽŽ‘:¿1.0.4–?ý=>“1.0.5Ž¨¬ïhtml:ï html:ŸC‘:No‘?ýchanges.ŽŸ8äïhtml:ï html:¡ïhtml:ï html:Ÿ ý‘0ïcolor push BlackÁlï color popŽŽ‘:¿1.0.3–?ý=>“1.0.4Ž¦ïhtml:ï html:ŸC‘:The–?ýname“of“this“library“is“now“ïhtml:ï html:ïhtml:ï html:Éobjectbase¿,“it“is“has“been“renamed“from“ïhtml:ï html:ïhtml:ï html:Éswarmob-Ž¤‘Hject–?ý¿largely“to“reflect“the“more“generic“nature“of“the“library“and“also“motivatedŽ¡‘Hby–?ýthe“impending“port“of“Swarm“to“Windows“NT“(to“avoid“filename“conflicts“withŽ¡‘Hthe–?ýïhtml:ï html:ÂSwarmObject“¿class).‘ úThere“should“be“little,“or“no“effect“on“the“user,“theŽ¡‘Honly–?ývisible“change“is“the“fact“that“the“actual“library“(.a)“or“(.so)“file“willŽ¡‘Hnow–?ýhave“a“different“name“and“the“header“file“name“has“changed.‘ úA“symbolic“linkŽ¡‘Hfrom–?ýïhtml:ï html:Âobjectbase.h“¿to“ïhtml:ï html:Âswarmobject.h“¿has“been“provided“in“the“distribution,“toŽ¡‘Hensure–?ýbackwards“compatibility,“however,“users“should“ïhtml:ï html:not“continue“to“rely“onŽ¡‘Hthis–?ýbeing“so.‘ úUsers“should“port“references“to“ïhtml:ï html:Âswarmobject.h“¿in“their“code“toŽ¡‘Hïhtml:ï html:Âobjectbase.h¿,–?ýbecause“this“symlink“will“be“removed“in“a“future“release.ŽŸ8äïhtml:ï html:ïhtml:ï html:ïhtml:ï html:© ý‘:Note:‘ úthis–?ýis“no“way“affects“the“ïhtml:ï html:ÂSwarmObject“¿class“which“remains“the“same“as“inŽ¡‘Hall–?ýprevious“releases.ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:¿1.0.0–?ý=>“1.0.1Žž¬ïhtml:ï html:ŸC‘:The–?ýinterface“has“changed“again!‘ úïhtml:ï html:¾EmptyProbeMap‘üo¿is“now“a“subclass“of“ïhtml:ï html:¾CustomProbeMap‘¼r¿,Ž¡‘Hwhich–?ýis“subclassed“from“ïhtml:ï html:¾ProbeMap‘¼r¿.› úAnd“a“shortcut“ïhtml:ï html:Âcreate:˜¿method“was“addedŽ¡‘Hto–?ýthat“branch.Žïhtml:ï html:Ÿ5ï‘:Also,–?ýa“new“method“was“added“to“ïhtml:ï html:¾ProbeLibrary‘üo¿called“ïhtml:ï html:ÂisProbeMapDefinedFor“¿that“servesŽ¡‘Hto–?ýnon-invasively“test“for“the“existence“of“a“ïhtml:ï html:¾ProbeMap‘üo¿for“a“given“class.ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¾Beta‘üo¿=>‘?ý1.0.0Žž¬ïhtml:ï html:ŸC‘:The–?ýnew“interface“for“the“ïhtml:ï html:¾swarmobject‘üo¿library“might“cause“some“problems“for“appsŽ¡‘Hthat–?ýworked“under“the“Beta“release“of“Swarm.‘ úTo“get“the“whole“scoop,“read“theŽ¡‘Hïhtml:ï html:Library–?ýInterface“Conventionsïhtml:ï html:Ž¤5ï‘:(defobj/library.html)Ž¡‘:.› úTo–?ýget“a“few“hints“at“explicit“changes“you“might“need“to“make,“check“out:˜ïhtml:ï html:PortingŽŸ‘Happs–?ýto“use“the“new“ïhtml:ï html:¾swarmobject‘üo¿interfaceïhtml:ï html:Ž¡‘:(objectbase/PortingAppsToNewInterface.html)Ž¡‘:.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¸g “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:Ÿ}ÀOv•ÓÅer“viewŽ©¿H¿The–?ýïhtml:ï html:¾objectbase‘üo¿library“encapsulates“various“fundamental“aspects“of“the“ïhtml:ï html:Swarm“object“modelŽ¤and–?ýdefines“the“probing“machinery“used“to“take“data“from“ïhtml:ï html:Swarm“objects.‘ úMost“of“the“underlyingŽ¡functionality–?ýof“the“classes“defined“here“is“contained“in“the“ïhtml:ï html:ïhtml:ï html:¾defobj‘¼rïhtml:ï html:Ž¦(defobj.html)Ž¤a¿and‘?ýïhtml:ï html:ïhtml:ï html:¾activity‘¼rïhtml:ï html:Ž¡(activity.html)Ž¡¿libraries.ŽŸïhtml:ï html:¡‘0The–?ýmain“classes“defined“here“that“are“intended“to“be“subclassed“by“users“are“SwarmŽ¤‘0and–?ýSwarmObject.‘ úThe“probing“functionality“provided“here“is“mainly“for“use“withinŽ¡‘0the–?ýïhtml:ï html:Swarm“kernel.‘ úHowever,“this“probe“machinery“should“be“used“when“designing“anyŽ¡‘0interface–?ýbetween“ïhtml:ï html:Swarm“and“any“other“agent“or“device.Ž©ŸJïhtml:ï html:ŸoÝÅSwarmObjectŽŸ‘ýïhtml:ï html:Ÿº›¾SwarmObject‘üo¿is–?ýthe“base“class“for“all“interactive“agents“in“ïhtml:ï html:Swarm.‘ úIt“defines“the“standardŽ¤G®behavior–?ýfor“Swarmstyle“agents,“which“includes“hooks“for“creation,“probing,“zoned“memory“allocation,Ž¡and‘?ýdestruction.ŽŸffïhtml:ï html:Ÿ¨ÁÅSwarmŽŸL˜¿The–?ýïhtml:ï html:¾Swarm›üo¿class“encapsulates“all“of“the“abstract“execution“machinery“in“the“ïhtml:ï html:¾activity˜¿library,Ž¡as–?ýwell“as“the“notion“of“a“group“of“related“objects.‘ úMetaphorically,“a“"Swarm"“is“a“combinationŽ¡of–?ýa“collection“of“objects“and“a“schedule“of“activity“over“those“objects.‘ úHence,“the“ïhtml:ï html:¾SwarmŽ¡¿class–?ýprovides“the“behavior“necessary“for“creating“such“an“object“and“starting“up“the“schedule.Ž¦ïhtml:ï html:ŸoÝÅPr½«obesŽ©ê¿Probes–?ýare“idealized“entities“that“are“intended“to“allow“the“user“to“monitor“and“modify“theŽ¤innards–?ýof“objects“without“explicitly“providing“the“functionality“to“do“so“at“compile“time.Ž¡Hence,–?ýthey“allow“dynamic“interaction“with“an“objects“instance“variables“and“methods.‘ úMostŽ¡of–?ýthe“functionality“of“probes“is“implemented“here;“but,“at“present,“they“are“intimately“linkedŽ¡to–?ýthe“ïhtml:ï html:ïhtml:ï html:¾simtools‘¼rïhtml:ï html:Ž¦(simtools.html)ŽŸa¿library,–?ýwhich“contains“all“the“widgetry“needed“to“use“probes“from“a“GUI.“Despite“this“intimacy,Ž¡probes–?ýare“intended“to“be“a“general“purpose“mechanism“for“ïhtml:ï html:any“agent“or“device“to“interact“dynamicallyŽ¡with–?ýïhtml:ï html:Swarm“objects.‘ úThis“ïhtml:ï html:ïhtml:ï html:Introduction“to“Probesïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¹"ú “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿(probing.html)Ž¤ºâwill–?ýexplain“more“about“the“reasoning“and“purpose“behind“probes.ŽŸ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:Ÿ¼jÀDocumentationŽ©^5¿The–?ýïhtml:ï html:¾objectbase‘üo¿library“is“defined“and“documented“following“the“basic“structure“of“the“ïhtml:ï html:LibraryŽ¡Interface‘?ýConventionsïhtml:ï html:Ž¦(defobj/library.html)Ž¡.‘ úThe–?ýfollowing“standard“sections“of“documentation“are“available:ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:© Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface‘?ýReferenceïhtml:ï html:Ž¡‘0(objectbase/Interface.html)ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Usage‘?ýGuideïhtml:ï html:Ž¡‘0(objectbase/UsageGuide.html)ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Advanced–?ýUsage“Notesïhtml:ï html:Ž¡‘0(objectbase/AdvancedUsage.html)ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface–?ýDesign“Notesïhtml:ï html:Ž¡‘0(objectbase/InterfaceDesign.html)ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Implementation‘?ýNotesïhtml:ï html:Ž¡‘0(objectbase/Implementation.html)ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:¦‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹º/Ò “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Objectbase–/Library:‘m™Documentation“andŽŸâImplementation‘/StatusŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹»7æ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Swarmobject–/Library:‘m™P•Üorting“A‘ÿ{Jpps“to“the“NewŽŸâInterfaceŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:ŸÑ‘0¿The–?ýproblems“that“might“arise“because“of“this“new“interface“should“have“to“do“withŽ¤‘0the–?ýplacement“or“existence“of“C“preprocessor“ïhtml:ï html:Â#import¿s.‘ úIn“the“beta“release,“theŽ¡‘0ïhtml:ï html:Âobjectbase.h–?ý¿file“simply“included“all“the“header“files“for“each“class“defined“inŽ¡‘0the–?ýïhtml:ï html:objectbase“library.‘ úThese“files“contain“the“ïhtml:ï html:Â@interface“¿declarations“for“eachŽ¡‘0respective–?ýclass.‘ úHence,“before,“if“an“application“file“included“ïhtml:ï html:Âobjectbase.h¿,“itŽ¡‘0was–?ýincluding“the“interface“for“every“class“in“the“library.ŽŸ8äïhtml:ï html:© ˜'‘0The–?ýSwarm“standard“module“interface“uses“Objective-C“protocols“to“establish“whichŽ¡‘0messages–?ýmay“be“sent“to“objects“of“a“class.‘ úDoing“this“isolates“the“classes“in“theŽ¡‘0library–?ýmore“completely“from“the“rest“of“the“code.‘ úSo,“the“problems“that“are“likelyŽ¡‘0to–?ýarise“from“this“new“interface“are“ones“of“access“to“objects“that“reside“in“theŽ¡‘0ïhtml:ï html:objectbase–?ýlibrary.‘ úAnd“they“are“of“two“types:ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push Black1.ï color popŽŽ‘<Messages–?ýthat“are“no“longer“available“on“one“or“more“classes“where“they“were“availableŽ¡‘<before.– úI.e.“you–?ýsee“warnings“like“the“following“when“you“compile“your“app:ŽŸ8äïhtml:ï html:¦‘$Âwarning:–ff`ClassName'“does“not“respond“to“`messageName'ŽŸbÌïhtml:ï html:Ÿn?‘<¿What–?ýthis“means“is“that“since“ïhtml:ï html:Âobjectbase.h“¿simply“imported“all“the“class“headerŽ¡‘Hfiles,–?ýsomewhere“in“that“chaotic“mess“of“an“import“tree,“the“header“for“the“ïhtml:ï html:ÂClass-Ž¡‘HName–?ý¿was“imported.‘ úNow,“since“ïhtml:ï html:Âobjectbase.h“¿only“defines“protocols“for“the“classesŽ¡‘Hit–?ýcontains,“it“no“longer“imported“that“header“file.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘<Solution–?ý#1:‘ úIf“ïhtml:ï html:ÂClassName“¿is“a“member“of“the“ïhtml:ï html:objectbase“library,“then“all“youŽ¡‘Hneed–?ýto“do“is“import“ïhtml:ï html:Âobjectbase.h“¿in“the“file“where“that“class“(or“an“instanceŽ¡‘Hof–?ýit)“is“used.‘ úIf,“however,“the“class“in“question“is“a“member“of“some“otherŽ¡‘Hlibrary,–?ýthen“you“should“find“out“which“library“it“is“a“member“of“and“includeŽ¡‘Hthe–?ýappropriate“header“file.‘ ú(This“latter“case“is“actually“part“of“the“justificationŽ¡‘Hfor–?ýmaking“these“libraries“into“"modules"“like“this....‘ úto“avoid“incestuousŽ¡‘Hinclude‘?ýtrees.)ŽŸÕSïhtml:ï html:Ÿû¸‘<Another–?ýcase“where“this“occurs“is“when“using“objects“that“have“been“staticallyŽ¡‘Htyped–?ýwith“a“class“name.‘ úIn“using“the“protocols“instead“of“direct“class“interfaces,Ž¡‘Hwe–?ýare“depriving“the“compiler“of“the“ability“to“analyze“the“type“of“an“objectŽ¡‘Hand–?ýdecide“if“that“object“can“accept“a“given“message.‘ úThis“is“a“bit“counterŽ¡‘Hintuitive–?ýfor“those“of“us“reared“with“strongly“typed“languages“and“styles.‘ úBut,Ž¡‘HSwarm–?ýtakes“advantage“of“the“freedom“this“allows“and“it“is“part“of“ïhtml:ï html:Swarm-styleŽ¡‘Hprogrammingïhtml:ï html:Ž¤Ñ‘<(../defobj/style.html)Ž¡‘<.Žïhtml:ï html:ïhtml:ï html:¡‘<Solution–?ý#2:‘ úIf“this“is“what's“happening“to“generate“the“above“warning,“thereŽ¤‘Hare–?ýtwo“further“degradations“of“typing“available.‘ úThe“next“step“down“is“to“takeŽ¡‘Haway–?ýthe“specific“class“type“and“replace“it“with“a“protocol“qualification“onŽ¡‘Ha–?ýpure“ïhtml:ï html:Âid“¿type.‘ úFor“example:ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¼:5 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘#ºâÂProbeMap–ff*“myProbeMap;Ž¤‘/ºâ¿can–?ýbe“changed“toŽºâ©8äïhtml:ï html:Ÿ Ç‘$Âid–ff“myProbeMap;Ž¡‘0¿This–?ýboth“allows“the“freedom“from“the“static“typing“ïhtml:ï html:and“adds“to“the“readibility“ofŽ¡‘<the–?ýcode.‘ úHowever,“this“still“results“in“compile“time“checking“for“messages“sentŽ¡‘<to–?ýthat“object“with“the“protocol“designated.‘ úSo,“any“message“you“intend“to“sendŽ¡‘<to–?ýthat“object“must“be“defined“or“inherited“by“the“given“protocol.‘ úSo,“in“someŽ¡‘<cases,–?ýone“may“want“to“go“with“the“ultimate“freedom“inŽ¦ïhtml:ï html:© Ç‘$Âid‘ffmyProbeMap;Ž¡‘0¿which,–?ýobviously,“means“the“compiler“will“not“second“guess“the“programmer“in“whatŽ¡‘<messages–?ýcan“be“sent“to“that“object.‘ úAnd“if“your“variables“are“named“appropriately,Ž¡‘<this–?ýdoesn't“really“detract“from“the“readibility“of“the“code.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push Black2.ï color popŽŽ‘<When–?ýsubclassing“from“a“class“defined“in“the“Swarm“Kernel,“it“is“necessary“to“importŽ¡‘<the–?ýïhtml:ï html:Â@interface“¿of“that“class.‘ úBefore,“when“ïhtml:ï html:Âobjectbase.h“¿included“all“those“interfaces,Ž¡‘<it–?ýwas“the“only“file“needed“if“you“wanted“to“subclass“from“a“class“in“ïhtml:ï html:objectbase.Ž¡‘<Now,–?ýhowever,“simply“importing“ïhtml:ï html:Âobjectbase.h“¿doesn't“help“at“all.‘ úSo,“in“orderŽ¡‘<to–?ýsubclass“from“a“class“that's“a“member“of“ïhtml:ï html:objectbase,“you“need“to“import“theŽ¡‘<specific–?ýinterface“file“to“that“class.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘<The–?ýsolution:‘ úIf“you“had“an“app“that“worked“before“when“you“subclassed“from“somethingŽ¡‘H(say,–?ýïhtml:ï html:Swarm)“in“ïhtml:ï html:objectbase“but“doesn't“work“now,“simply“replace“theŽŸ8äïhtml:ï html:¦‘$Â#import‘ffŽ¡‘0¿in–?ýthe“header“file“for“the“subclass“withŽŸïhtml:ï html:¡‘$Â#import‘ffŽŸbÌïhtml:ï html:ïhtml:ï html:Ÿ 4‘<¿Note:‘ úIn–?ýorder“to“reduce“the“number“of“broken“apps“due“to“this,“we've“explicitlyŽ¡‘Himported–?ýïhtml:ï html:Âobjectbase/SwarmObject.h“¿and“ïhtml:ï html:Âobjectbase/Swarm.h¿at“the“end“of“the“ïhtml:ï html:Âob-Ž¡‘Hjectbase.h–?ý¿file.‘ úThis“allows“the“subclassing“of“ïhtml:ï html:SwarmObject“or“ïhtml:ï html:Swarm“by“an“importŽ¡‘Hof–?ýïhtml:ï html:Âobjectbase.h“¿without“the“explicit“import“of“the“interface“files.‘ úBut,“thisŽ¡‘Hwas–?ýdone“for“backward“compatibility“and“may“go“away“in“the“future.‘ úSo“pleaseŽ¡‘Hsubclass–?ýby“explicit“importation“of“the“interface“file“of“the“class.ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:¦‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹½K “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Objectbase–/Library:‘m™Interface“Refer |enceŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¿The–?ýïhtml:ï html:¾objectbase‘üo¿library“uses“the“ïhtml:ï html:module“definition“conventionsïhtml:ï html:Ž¡‘0(../defobj/module.html)Ž¡‘0established–?ýby“the“ïhtml:ï html:ïhtml:ï html:¾defobj‘üo¿libraryïhtml:ï html:Ž¡‘0(../defobj.html)Ž¡‘0.‘ úIt–?ýalso“depends“on“standard“supertypes“and“classes“defined“by“this“library.ŽŸ€’ïhtml:ï html:Ÿœ›ÀDependenciesŽŸwJ¿Following–?ýare“the“other“header“files“imported“by“:ŽŸ—ïhtml:ï html:Ÿïhtml:ï html:Ÿ à1‘0Â#import‘ffŽ¡‘0#import‘ff;Ž¡¿The–?ýïhtml:ï html:¾defobj‘üo¿library“interface“is“included“to“provide“the“basic“object“support.‘ úThe“ïhtml:ï html:¾SwarmObjectŽ¤¿class–?ýheader“file“was“provided“for“backward“compatibility“since“the“ïhtml:ï html:¾objectbase‘üo¿library“hasŽ¡been–?ýbrought“into“agreement“with“the“library“standards.ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸÕÀObject–QëT‘þ¸¦ypes“(with“links“to“r•°gefer“ence‘Qëpages)ŽŸ âcïhtml:ï html:ïhtml:ï html:Ÿ”ç‘0ÂSwarmObjectïhtml:ï html:Ž¤‘5ff(SwarmObject.html)Ž¡’–™’/–ÿþ|“\Ž¡’‘3,/– fd|“\‘f™’ïhtml:ï html:ProbeLibraryïhtml:ï html:Ž¡‘5ff(ProbeLibrary.html)Ž¡’‹ÌÆ/–%ÌÊ|“\Ž¡‘:ÌÌïhtml:ï html:ActivityControlïhtml:ï html:Ž¡‘5ff(ActivityControl.html)Ž¡‘Pfdïhtml:ï html:Probeïhtml:ï html:Ž¡‘5ff(Probe.html)Ž¡‘Pfdïhtml:ï html:ProbeMapïhtml:ï html:Ž¡‘5ff(ProbeMap.html)Ž¡’¦ÌÄ/–32|‘+30|‘ ÌÌ\“\Ž¡’›ÿø/‘ÿþ|‘+30|‘32\‘™˜\Ž¡’‘3,/‘%ÌÊ|‘+30|‘™˜\‘ÿþ\Ž¡’†f`/‘0™–|‘+30|‘ÿþ\‘ fd\Ž¡‘[30ïhtml:ï html:VarProbeïhtml:ï html:Ž¡‘5ff(VarProbe.html)Ž¡‘UÌÊïhtml:ï html:Messageïhtml:ï html:Ž¡‘5ff(MessageProbe.html)Ž¡‘@32ïhtml:ï html:Customïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¾X“ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘5!HÂ(CustomProbeMap.html)Ž¤4²‘ETz\‘ fdïhtml:ï html:Completeïhtml:ï html:Ž¡‘5!H(CompleteVarMap.html)Ž¡’±Trïhtml:ï html:Probeïhtml:ï html:Ž¡‘5!H(MessageProbe.html)Ž¡‘ETzïhtml:ï html:Probeïhtml:ï html:Ž¡‘5!H(CustomProbeMap.html)Ž¡‘Jºà\‘%ÌÊïhtml:ï html:Varïhtml:ï html:Ž¡‘5!H(CompleteVarMap.html)Ž¡’çTnïhtml:ï html:Mapïhtml:ï html:Ž¡‘5!H(CustomProbeMap.html)Ž¡‘U‡¬\‘%ÌÊïhtml:ï html:Mapïhtml:ï html:Ž¡‘5!H(CompleteVarMap.html)Ž¡’‡žïhtml:ï html:Completeïhtml:ï html:Ž¡‘5!H(CompleteProbeMap.html)Ž¡’îïhtml:ï html:Probeïhtml:ï html:Ž¡‘5!H(CompleteProbeMap.html)Ž¡’Tjïhtml:ï html:Mapïhtml:ï html:Ž¡‘5!H(CompleteProbeMap.html)Ž¡ºâ¿(don't–?ýwant“a“graphic“with“image“map“to“avoid“excessive“download“times!)Žºâ©8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:ŸñÀContents:ŽŸ ¢Âïhtml:ï html:Ÿïhtml:ï html:Ÿð%‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SwarmObjectïhtml:ï html:Ž¡‘0(SwarmObject.html)Ž¦ïhtml:ï html:Ÿ ûÎ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ProbeLibraryïhtml:ï html:Ž¡‘0(ProbeLibrary.html)Ž¦ïhtml:ï html:Ÿ ûÎ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ActivityControlïhtml:ï html:Ž¡‘0(ActivityControl.html)Ž¦ïhtml:ï html:Ÿ ûÎ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Probeïhtml:ï html:Ž¡‘0(Probe.html)ŽŸÕSïhtml:ï html:Ÿ__‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ProbeMapïhtml:ï html:Ž¡‘0(ProbeMap.html)Ž¦ïhtml:ï html:Ÿ ûÎ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿VarProbeïhtml:ï html:Ž¡‘0(VarProbe.html)ŽŸÕSïhtml:ï html:Ÿ__‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿MessageProbeïhtml:ï html:Ž¡‘0(MessageProbe.html)Ž¦ïhtml:ï html:Ÿ ûÎ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿CustomProbeMapïhtml:ï html:Ž¡‘0(CustomProbeMap.html)Ž¦ïhtml:ï html:Ÿ ûÎ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿CompleteProbeMapïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹¿bŽ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿(CompleteProbeMap.html)Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(../objectbase.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(../objectbase.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(UsageGuide.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÀnS “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½SwarmObject‘/ClassŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤Fy‘0Â//Ž¡‘0//–ffSwarmObject“--Ž¡‘0//‘32Superclass–ffof“most“objects“in“a“Swarm“simulation.Ž¡‘0//‘32Provides–ffsupport“for“probing.Ž¡‘0//Ž¡‘0@protocol–ffSwarmObject“Ž¡‘0USINGŽ¡‘0-–ff(const“char*)getInstanceName;Ž¡‘0-‘ffgetProbeMap;Ž¡‘0-‘ffgetCompleteProbeMap;Ž¡‘0-–ffgetProbeForVariable:“(const“char“*)aVariable;Ž¡‘0-–ffgetProbeForMessage:“(const“char“*)aMessage;Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¿A–?ýïhtml:ï html:SwarmObject“is“an“object“that“is“intended“to“be“a“member“of“a“ïhtml:ï html:Swarm.‘ úThat“is,“itsŽ¤‘0behavior–?ýwill“be“perpetuated“by“messages“sent“from“the“schedule“of“events“definedŽ¡‘0in–?ýthe“context“of“a“ïhtml:ï html:Swarm“object.ŽŸ8äïhtml:ï html:© •‘0The–?ýïhtml:ï html:SwarmObject“is“where“the“models“of“all“the“agents“of“a“simulation“will“reside.Ž¡‘0Hence,–?ýmost“of“the“burden“on“defining“the“messages“that“can“be“sent“to“any“agent“liesŽ¡‘0with–?ýthe“user.‘ úïhtml:ï html:SwarmObject“inherits“its“basic“functionality“from“the“ïhtml:ï html:Create“and“ïhtml:ï html:DropŽ¡‘0object–?ýtypes“defined“in“the“ïhtml:ï html:defobj“library.‘ úIt“is“useful“to“mention“these“messagesŽ¡‘0here–?ýto“show“the“complete“span“of“messages“that“can“dictate“the“behavior“of“an“instanceŽ¡‘0of–?ýa“ïhtml:ï html:SwarmObject;“but“it“is“not“useful“to“explain“their“function“in“detail.‘ úThe“messagesŽ¡‘0ïhtml:ï html:SwarmObject–?ýinherits“from“ïhtml:ï html:defobj“are:ŽŸ8äïhtml:ï html:¤ïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:¿DefinedObjectŽŸ8äïhtml:ï html:¡ïhtml:ï html:¦‘:ïcolor push Blackó!\ùðff pzdrÌlï color popŽŽ‘D¿-‘?ýgetType;Ž¤8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ýgetClass;Ž¡ïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ý(BOOL)respondsTo:‘ ú(SEL)aSel;Ž¡ïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ýdescribe:‘ úanOutputStream;Ž¡ïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-–?ý(BOOL)setDisplayNameTo:‘ ú(const“char“*)aName;Ž¡ïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-–?ý(const“char“*)getDisplayName;Ž¡ïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ýcreateIDString:‘ úaZone;ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:¿CreateŽŸ¬ïhtml:ï html:Ÿïhtml:ï html:Ÿ)Í‘:ïcolor push BlackÌlï color popŽŽ‘D¿+‘?ýcreate:‘ úaZone;ŽŸcïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÁrU “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘9ºâïcolor push BlackÌlï color popŽŽ‘Cºâ¿+‘?ýcreateBegin:‘ úaZone;Žºâ¤8äïhtml:ï html:© £W‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ýcreateEnd;ŽŸcïhtml:ï html:Ÿx®‘:ïcolor push BlackÌlï color popŽŽ‘D¿+‘?ýcustomizeBegin:‘ úaZone;Ž¡ïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ýcustomizeEnd;ŽŸcïhtml:ï html:Ÿx®‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ýcustomizeCopy:‘ úaZone;ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:¿DropŽ¡ïhtml:ï html:Ÿïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ýgetZone;Ž¡ïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘D¿-‘?ý(void)drop;ŽŸ8äïhtml:ï html:¦‘0In–?ýaddition“to“these,“ïhtml:ï html:SwarmObject“is“augmented“by“the“messages“that“provide“the“probeŽŸ‘0support.Ž¡ïhtml:ï html:ïhtml:ï html:¦‘0getInstanceName–?ýis“a“message“used“by“the“probe“machinery“to“get“a“meaningful“wordŽ¤‘0or–?ýphrase“to“indicate“the“object“being“probed“(and,“in“the“case“of“a“probe“display,Ž¡‘0place–?ýit“in“a“widget“on“the“screen).‘ úSupport“for“this“has“recently“been“added“toŽ¡‘0the–?ýïhtml:ï html:DefinedObject“object“type,“thereby“making“it“more“generally“available.‘ úSo,“thisŽ¡‘0message–?ýwill“likely“become“obsolete“soon.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘0getProbeMap–?ýreturns“a“pointer“to“the“ïhtml:ï html:ProbeMap“for“the“object“if“there“has“been“oneŽ¡‘0created–?ýfor“that“object's“class.‘ úIf“it“hasn't,“then“it“create's“a“default“one.Ž¤8äïhtml:ï html:ïhtml:ï html:¦‘0getCompleteProbeMap–?ýreturns“a“newly“created“ïhtml:ï html:CompleteProbeMap“for“the“object.Ž¡ïhtml:ï html:ïhtml:ï html:¦‘0getProbeForVariable:‘ ú(const–?ýchar“*)aVariable“returns“the“ïhtml:ï html:VarProbe“indexed“in“theŽŸ‘0ïhtml:ï html:ProbeMap–?ýby“the“string“ïhtml:ï html:aVariable.Ž¡ïhtml:ï html:ïhtml:ï html:¦‘0getProbeForMessage:‘ ú(const–?ýchar“*)aMessage“returns“the“ïhtml:ï html:MessageProbe“indexed“in“theŽŸ‘0ïhtml:ï html:ProbeMap–?ýby“the“string“ïhtml:ï html:aMessage.ŽŸ‘0„¤ŽŽ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:ŸÜ;(Interface.html)ŽŸÕSïhtml:ï html:¦’áøRïï html:ŸÜ;(../objectbase.html)ŽŸ8äïhtml:ï html:¦’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:ŸÜ;(ProbeLibrary.html)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Â “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ã‹ù “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Pr |obeLibrary‘/ClassŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤a‰‘0Â//Ž¡‘0//–ffProbeLibrary“--Ž¡‘0//–ffA“(singleton)“Class,“whose“instance“is“used“as“a“container“for“aglobalŽ¡‘0//–ffmapping“between“classnames“and“their“'default'“ProbeMaps.“These“defaultsŽ¡‘0//–ffcan“be“changed“by“the“user,“thus“allowing“him/her“to“customize“the“defaultŽ¡‘0//–ffcontents“of“the“ProbeDisplays“generated“when“probing“objects.Ž¡‘0//Ž¡‘0@protocol–ffProbeLibrary“Ž¡‘0USINGŽ¡‘0-–ffsetDisplayPrecision:“(int)“nSigDisplay;Ž¡‘0-‘ff(int)getDisplayPrecision;Ž¡‘0-–ffsetSavedPrecision:“(int)“nSigSaved;Ž¡‘0-‘ff(int)getSavedPrecision;Ž¡‘0-–ff(BOOL)isProbeMapDefinedFor:“(Class)aClass;Ž¡‘0-–ffgetProbeMapFor:“(Class)aClass;Ž¡‘0-–ffgetCompleteProbeMapFor:“(Class)aClass;Ž¡‘0-–ffgetCompleteVarMapFor:“(Class)aClass;Ž¡‘0-–ffgetProbeForVariable:“(const“char“*)aVar“inClass:“(Class)aClass;Ž¡‘0-–ffgetProbeForMessage:“(const“char“*)aMessage“inClass:“(Class)aClass;Ž¡‘0-–ffsetProbeMap:“aMap“For:“(Class)aClass;Ž¡‘0@endŽ¡¡‘0extern–ffid““probeLibrary;ŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¿The–?ýnormal“Swarm“simulation“will“probably“only“ever“contain“one“instance“of“this“class,Ž¤‘0namely–?ýthe“ïhtml:ï html:¾probeLibrary‘üo¿object.‘ úThis“object“is“used“for“Library“Generation“of“ïhtml:ï html:¾Probe‘¼r¿sŽ¡‘0and–?ýïhtml:ï html:¾ProbeMaps‘¼r¿:‘ úits“role“is“to“cache“one“unique“"official"“ïhtml:ï html:¾ProbeMap‘üo¿for“every“ClassŽ¡‘0ever–?ýprobed“during“a“run“of“Swarm.‘ úThese“ïhtml:ï html:¾ProbeMap‘¼r¿s“are“generated“lazily“as“theyŽ¡‘0are‘?ýrequested.Ž¤8äïhtml:ï html:¦ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:© (¥‘:-‘?ýsetDisplayPrecision:‘ ú(int)nSigDisplayŽ¡ïhtml:ï html:¦‘XSets–?ýthe“number“of“significant“digits“for“floating“point“and“double“floatingŽ¤‘Xpoint–?ýnumbers“displayed“on“GUI“widgets.‘ úCurrently“only“implemented“for“ïhtml:ï html:ÂVarProbesŽ¡‘X¿not–?ýïhtml:ï html:ÂMessageProbes“¿as“yet.‘ úThis“allows“ïhtml:ï html:¾all‘üo¿probes“checked“out“the“globalŽ¡‘XProbeLibrary–?ýinstance“to“access“this“displayed“precision.‘ úHowever,“individualŽ¡‘Xprobes–?ýcan“vary“from“this“global“default,“by“using“the“ïhtml:ï html:ÂsetFloatFormat“¿methodŽ¡‘Xon–?ýa“exisiting“probe.‘ úSee“ïhtml:ï html:probing“precisionïhtml:ï html:Ž¤a‰‘X(../probing.html#precision)Ž¡‘Xfor–?ýmore“details“on“how“to“do“this.ŽŸïhtml:ï html:ïhtml:ï html:¡‘:-‘?ý(int)getDisplayPrecisionŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÄÚ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Wºâ¿Gets–?ýthe“current“display“precision“set“in“the“ProbeLibrary“instance.‘ úMostlyŽ©‘Wºâused‘?ýinternally.ŽºâŸ8äïhtml:ï html:ïhtml:ï html:¤ ´´‘:-‘?ýsetSavedPrecision:‘ ú(int)nSigSavedŽŸ8äïhtml:ï html:¡‘XSets–?ýthe“number“of“significant“digits“saved“for“floating-point“and“doubleŽ¦‘Xfloating-point–?ýnumbers“through“ObjectSaver.‘ úThis“function“sets“the“globalŽ¦‘Xdefault–?ýprecision“for“all“floating“(and“double“floating)“point“numbers.‘ úThisŽ¦‘Xfloating–?ýpoint“precision“affects“all“numbers“saved“via“the“ObjectSaver“class.Ž¦‘XThere–?ýis“currently“no“way“to“override“this“global“default“for“an“individualŽ¦‘Xprobe.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:-(int)‘?ýgetSavedPrecisionŽŸ8äïhtml:ï html:¡‘XGets–?ýthe“current“saved“precision“set“in“the“ProbeLibrary“instance.‘ úMostlyŽ¦‘Xused‘?ýinternally.ŽŸ8äïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¡‘0Note:‘ úif–?ýïhtml:ï html:ïhtml:ï html:neither“of“these“methods“are“used“to“set“the“defaults,“the“precision“inŽ¦‘0ïhtml:ï html:ïhtml:ï html:both–?ýcases“defaults“to“ïhtml:ï html:six“(6)“significant“figures,“which“should“simulate“the“defaultŽ¦‘0precision–?ýbefore“the“introduction“on“this“feature“ïhtml:ï html:¾on“most“platforms‘¼r¿.‘ úPreviously,Ž¦‘0the–?ýsprintf“"%g"“default“format“was“used“to“print“out“floats“and“doubles,“which“isŽ¦‘0not–?ýconsidered“to“have“entirely“portable“behavoir.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:-–?ý(BOOL)“isProbeMapDefinedFor:‘ ú(Class)“aClass“returns“ïhtml:ï html:ÂTrueŽŸ8äïhtml:ï html:¡‘X¿If–?ýthere“is“a“non-nil“value“in“the“ïhtml:ï html:¾ProbeLibrary‘üo¿for“that“class“and“ïhtml:ï html:ÂFalseŽ¦‘X¿otherwise.ŽŸïhtml:ï html:ïhtml:ï html:Ÿí˜‘:-‘?ýgetProbeMapFor:‘ ú(Class)aClassŽŸ8äïhtml:ï html:¡‘Xreturns–?ýa“ïhtml:ï html:¾ProbeMap›üo¿for“the“ïhtml:ï html:¾aClass˜¿class.‘ úIf“a“specific“ïhtml:ï html:¾ProbeMap˜¿has“beenŽ¦‘Xdesigned–?ýand“installed“in“the“ïhtml:ï html:¾ProbeLibrary‘üo¿for“that“class,“then“that“ïhtml:ï html:¾ProbeMapŽ¦‘X¿is–?ýreturned.‘ úIf“not,“then“a“ïhtml:ï html:¾CompleteProbeMap‘üo¿is“created“and“returned.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:-‘?ýgetCompleteProbeMapFor:‘ ú(Class)aClassŽŸ8äïhtml:ï html:¡‘XThis–?ýmethod“returns“a“ïhtml:ï html:¾ProbeMap‘üo¿containing“ïhtml:ï html:¾Probe‘¼r¿s“for“all“the“instance“variablesŽ¦‘Xand–?ýmessages“of“the“given“Class“(including“inherited“variables“and“messages).Ž¦‘XSince–?ýwe“are“assuming“that“normal,“single-level“ïhtml:ï html:¾ProbeMap‘¼r¿s“will“be“more“widelyŽ¦‘Xused,–?ýthe“current“implementation“of“ïhtml:ï html:¾ProbeLibrary‘üo¿does“not“cache“ïhtml:ï html:¾CompleteProbeMap‘¼r¿s.Ž¦‘XHowever,–?ýif“we“find“that“there“is“a“demand“for“ïhtml:ï html:¾CompleteProbeMap‘¼r¿s,“we“willŽ¦‘Xcache–?ýthem“as“well.ŽŸïhtml:ï html:ïhtml:ï html:Ÿí˜‘:-‘?ýgetCompleteVarMapFor:‘ ú(Class)aClassŽŸ8äïhtml:ï html:¡‘XThis–?ýmethod“returns“a“ïhtml:ï html:¾ProbeMap‘üo¿containing“Probes“for“all“the“instance“variablesŽ¦‘Xof–?ýthe“given“Class“(including“inherited“variables)“but“does“ïhtml:ï html:not“include“anyŽ¦‘Xïhtml:ï html:¾MessageProbe‘¼r¿s.Ž©8äïhtml:ï html:ïhtml:ï html:¡‘:-–?ýgetProbeForVariable:› ú(const“char“*)aVariable“inClass:˜(Class)aClassŽ¦ïhtml:ï html:ïhtml:ï html:¡‘:-–?ýgetProbeForMessage:› ú(const“char“*)aMessage“inClass:˜(Class)aClassŽŸ8äïhtml:ï html:¡‘XThese–?ýmethods“are“used“to“"check“out"“the“appropriate“Probes“from“the“probeŽ¤‘Xlibrary.‘ úNote–?ýthat“the“returned“probes“will“be“cached,“so“you“must“make“sureŽ¡‘Xto–?ýclone“them“if“you“want“to“make“modifications“to“the“probes“ïhtml:ï html:without“affectingŽ¡‘Xthe–?ýresult“of“future“requests“for“those“same“probes.Ž¦ïhtml:ï html:ïhtml:ï html:Ÿ ´´‘:-–?ýsetProbeMap:› úaMap“For:˜(Class)aClassŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÅšB “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Wºâ¿In–?ýthose“cases“where“the“user“wants“to“set“the“standard“probe“map“directly,Ž¤‘Wºâshe–?ýcan“provide“the“probe“map“using“this“method,“and“it“will“be“cached“asŽ¡‘Wºâthough–?ýit“were“produced“by“the“library“itself.Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(SwarmObject.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(Probe.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÆÉ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½ActiÊìvityContr |ol‘/ClassŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤µ1‘0Â//Ž¡‘0//–ffActivityControl“--“This“class“provides“an“object“interface“toŽ¡‘0//‘kÿøan–ffactivity.‘ ÌÌIt“contains“a“subset“of“the“messagesŽ¡‘0//‘kÿøthat–ffany“activity“responds“to“and“provides“explicitŽ¡‘0//‘kÿøcontrol–ffover“that“activity.Ž¡‘0//Ž¡‘0@protocol–ffActivityControl“Ž¡‘0CREATINGŽ¡‘0-–ffattachToActivity:“anActivity;Ž¡‘0USINGŽ¡‘0-‘ffrun;Ž¡‘0-‘ffstop;Ž¡‘0-‘ffnext;Ž¡‘0-‘ffstep;Ž¡‘0-–ffstepUntil:“(timeval_t)stopTime;Ž¡‘0-‘ff(void)terminate;Ž¡‘0-‘ffupdateStateVar;Ž¡‘0-‘ffgetStatus;Ž¡‘0-–ff(const“char“*)getInstanceName;Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¿The–?ýïhtml:ï html:ActivityControl“class“specifies“an“object“that“can“be“attached“to“an“activityŽ¤‘0(regardless–?ýof“how“or“where“that“activity“is“created)“for“the“purpose“of“explicitlyŽ¡‘0controlling–?ýthe“execution“of“actions“on“that“activity's“action“plan.‘ úThere“is“nothingŽ¡‘0that–?ýavailable“through“this“class“that“is“not“already“available“through“the“variablesŽ¡‘0or–?ýmessages“available“via“the“activity“itself.‘ úHowever,“it“packages“up“the“main“controlŽ¡‘0messages–?ýand“makes“them“available“to“other“objects“that“may“need“control“over“an“activity,Ž¡‘0thereby–?ýshielding“the“activity“from“directly“receiving“messages“from“outside“objectsŽ¡‘0and–?ýsaving“the“user“from“having“to“parse“the“more“complex“interface“to“the“activity.Ž©€’ïhtml:ï html:Ÿ8·ÀCrš°geate–QëPhase“Pr˜otocolsŽŸ ¢Âïhtml:ï html:ïhtml:ï html:Ÿp¤‘0¿attachToActivity:‘ úanActivity–?ýsets“an“instance“variable“inside“the“ïhtml:ï html:ActivityControlŽ¡‘0object–?ýthat“points“to“the“ïhtml:ï html:Activity“to“be“controlled.‘ úIt“then“creates“a“ïhtml:ï html:Schedule“uponŽ¡‘0which–?ýit“places“a“message“to“itself“to“update“its“own“variables.Ž¦ïhtml:ï html:Ÿ8·ÀUsage–QëPhase“Pr°gotocolsŽŸ âcïhtml:ï html:ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ç²… “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿run–?ýsends“a“ïhtml:ï html:run“message“to“the“activity“if“the“conditions“are“appropriate.‘ úThis“messageŽ¤‘/ºâcauses–?ýthe“activity“to“continue“executing“the“actions“on“it's“schedule“until“eitherŽ¡‘/ºâno–?ýother“actions“are“waiting,“at“which“point“it“returns“ïhtml:ï html:Completed,“or“until“it“isŽ¡‘/ºâïhtml:ï html:stopped–?ýby“a“subactivity“or“a“ïhtml:ï html:stop“message“to“the“activity.Žºâ©8äïhtml:ï html:ïhtml:ï html:Ÿ ¢£‘0stop–?ýsends“a“ïhtml:ï html:stop“message“to“the“activity“if“the“conditions“are“appropriate.‘ úThisŽ¡‘0message–?ýcauses“the“control“to“move“back“up“the“run-stack“and“resume“at“the“place“inŽ¡‘0the–?ýcode“where“the“ïhtml:ï html:run“was“first“executed,“which“doesn't“mean“much“in“a“parallel“executionŽ¡‘0context;–?ýbut,“in“a“serial“context,“it“means“that“the“next“action“on“the“super-activityŽ¡‘0will–?ýbegin“without“finishing“the“rest“of“the“current“activity's“actions.Ž¦ïhtml:ï html:ïhtml:ï html:Ÿ ¢£‘0next–?ýsends“a“ïhtml:ï html:next“message“to“the“activity“if“the“conditions“are“appropriate.‘ úIt“ïhtml:ï html:runsŽ¡‘0an–?ýactivity“forward“through“as“many“actions“as“necessary“until“it“hits“a“ïhtml:ï html:breakFunction,Ž¡‘0at–?ýwhich“point“it“walks“back“up“the“tree“of“activities“and“returns“ïhtml:ï html:Stopped.‘ úIn“mostŽ¡‘0cases,–?ýthis“means“that“an“entire“action“or“action“group“on“the“activity“under“controlŽ¡‘0will–?ýbe“executed,“including“completion“of“all“subactivities.Ž¦ïhtml:ï html:ïhtml:ï html:Ÿ ¢£‘0step–?ýsends“a“ïhtml:ï html:step“message“to“the“activity“if“the“conditions“are“appropriate.‘ úIt“causesŽ¡‘0the–?ýexecution“of“a“single“action.Ž¦ïhtml:ï html:ïhtml:ï html:Ÿ ¢£‘0stepUntil:› ú(timeval_t)stopTime–?ýsends“a“ïhtml:ï html:stepUntil:˜message“to“the“activity“if“conditionsŽ¡‘0are–?ýappropriate.‘ úThis“causes“all“actions“on“the“activity's“schedule,“including“anyŽ¡‘0actions–?ýon“subactivities'“schedules,“to“be“executed“until“the“activity's“relativeŽ¡‘0time–?ýis“equal“to“ïhtml:ï html:ÂstopTime–ff-“1¿.Ž¦ïhtml:ï html:ïhtml:ï html:Ÿ ¢£‘0(void)terminate–?ýsends“the“ïhtml:ï html:terminate“message“to“the“activity,“which“causes“all“actionsŽ¡‘0and–?ýaction“groups“to“be“removed“from“its“schedule.‘ úThis“can“cause“some“problems.Ž¡‘0If–?ýïhtml:ï html:terminate“is“sent“to“an“activity“and,“subsequently,“a“ïhtml:ï html:run“is“attempted“on“thatŽ¡‘0activity,–?ýthe“program“will“exit“with“an“error.‘ úA“way“to“avoid“this“might“be“to“eliminateŽ¡‘0the–?ýïhtml:ï html:ActivityControl“attached“to“the“terminated“activity;“but,“that“would“precludeŽ¡‘0the–?ýreuse“of“ïhtml:ï html:ActivityControllers“on“other“activities.‘ úIdeally,“a“controller“couldŽ¡‘0be–?ýadjusted“to“monitor“any“of“several“activities“and“it“could“leap“from“one“activityŽ¡‘0to–?ýanother.‘ úSo,“this“behaviour“is“advertised“as“a“ïhtml:ï html:feature.ŽŸcïhtml:ï html:ïhtml:ï html:Ÿwú‘0updateStateVar–?ýupdates“the“ïhtml:ï html:ActivityControl“instance“variables“and“tests“for“the“continuedŽ¡‘0existence–?ýof“the“activity“that's“being“controlled.‘ úThis“message“is“sent“on“each“cycleŽ¡‘0of–?ýthe“schedule“for“the“activity“being“controlled.Ž¦ïhtml:ï html:ïhtml:ï html:¤ ¢£‘0getStatus–?ýreturns“the“status“of“the“activity.Ž¦ïhtml:ï html:ïhtml:ï html:¡‘0(const–?ýchar“*)getInstanceName“This“method“is“provided“for“backwards“compatibilityŽ¤‘0to–?ýthe“probe“machinery.‘ úIt“echos“the“ïhtml:ï html:displayName“resident“in“the“object“name“database.Ž¡‘0When–?ýthe“probe“machinery“is“upgraded“to“use“this“database,“this“method“will“becomeŽ¡‘0obsolete.ŽŸ‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:ŸÛ‡(CompleteVarMap.html)ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹È¼ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÖ\’á³4ïï html:©¿(Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(UsageGuide.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÉÎq “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Pr |obe‘/ClassŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤"·‘0Â//Ž¡‘0//–ffProbe“--Ž¡‘0//‘32Abstract–ffsuperclass“of“both“VarProbe“and“MessageProbe.Ž¡‘0//Ž¡‘0@protocol–ffProbe“Ž¡‘0CREATINGŽ¡‘0-‘ffsetProbedClass;Ž¡‘0SETTINGŽ¡‘0-–ffsetSafety;‘ÿþ//“There“should“be“a“setSafety:“BOOLŽ¡‘0-–ffunsetSafety;‘32//“and“getSafety“methods“instead...Ž¡‘0USINGŽ¡‘0-–ffclone:“aZone;Ž¡‘0-‘ff(Class)getProbedClass;Ž¡‘0-–ff(const“char“*)getProbedType;Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¿A–?ýïhtml:ï html:Probe“is“simply“an“object“that“contains“pointers“to“an“element“(instance“variableŽ¤‘0or–?ýmessage“description)“of“another“object.‘ úThe“ïhtml:ï html:Probe“contains“instance“variablesŽ¡‘0that–?ýdescribe“the“referent's“class“and“type.‘ úIt's“actually“an“abstract“class“thatŽ¡‘0is–?ýfurther“subdivided“into“ïhtml:ï html:VarProbe“and“ïhtml:ï html:MessageProbe,“which“represent“the“two“basicŽ¡‘0types–?ýof“elements“of“any“object.‘ úThe“ïhtml:ï html:Probes“are“collected“into“a“ïhtml:ï html:ProbeMap“and“subsequentlyŽ¡‘0installed–?ýin“the“ïhtml:ï html:ProbeLibrary.Ž©€’ïhtml:ï html:Ÿ¦=ÀCrš°geate–QëPhase“Pr˜otocolŽŸ ¢Âïhtml:ï html:ïhtml:ï html:ŸÞ*‘0¿setProbedClass:‘ ú(Class)aClass–?ýsets“the“class“of“the“referent“and“ïhtml:ï html:must“be“called“atŽ¡‘0create‘?ýtime.ŽŸG®ïhtml:ï html:Ÿß!ÀSetting–QëPhase“Pr°gotocolŽŸ âcïhtml:ï html:ïhtml:ï html:Ÿž‰‘0¿setSafety–?ýturns“on“the“option“of“checking“the“compatibility“of“the“class“of“the“objectŽ¡‘0before–?ýany“actions“are“performed“on“the“referent.‘ úThis“is“only“used“in“the“ïhtml:ï html:VarProbesŽ¡‘0and–?ýshould“probably“be“moved.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ éÓ‘0unsetSafety–?ýturns“the“safety“option“off.Ž¦ïhtml:ï html:Ÿ¦=ÀRegular‘QëPr°gotocolŽŸ âcïhtml:ï html:ïhtml:ï html:Ÿž‰‘0¿(Class)getProbedClass–?ýreturns“the“class“of“the“referent“as“a“ïhtml:ï html:Class“pointer.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÊÑu “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ïhtml:ï html:© ‘0¿(const–?ýchar“*)getProbedType“returns“the“typing“of“the“probed“variable/message.‘ úTheŽ¤‘0typing–?ýis“represented“using“the“string-format“provided“by“the“Objective-C“runtimeŽ¡‘0system–?ý('c'“for“char,“'@'“for“id,“and“so“on).‘ úIn“general“the“programmer“will“knowŽ¡‘0the–?ýtyping“of“the“variable“so“this“method“will“probably“only“be“used“internally“byŽ¡‘0Swarm–?ýkernel“code.ŽŸïhtml:ï html:ïhtml:ï html:¡‘0clone:› úaZone–?ýreturns“a“clone“of“the“probe.˜It“is“useful“in“case“you“got“the“probeŽ¡‘0by–?ýLibrary“Generation“or“by“the“default“version“of“Object“Generation.‘ úIn“both“casesŽ¡‘0you–?ýwill“have“been“given“a“unique“shared“instance“of“the“probe“-“so“if“you“wantedŽ¡‘0to–?ýmake“changes“to“the“safety“status“of“the“probe“etc.‘ úwithout“affecting“the“otherŽ¡‘0potential–?ýusers“of“the“probe,“you“would“first“clone“it“and“then“make“the“requiredŽ¡‘0changes.Ž¤‘0„¤ŽŽ¦ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¦ïhtml:ï html:¡(ProbeLibrary.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¡(SwarmObject.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¦ïhtml:ï html:¡(VarProbe.html)Ž¡‘0„¤ŽŽ¦ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ËÛ¬ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½V‘þªarPr |obe‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤R‘0Â//Ž¡‘0//–ffVarProbe“--Ž¡‘0//–ffAllows“the“user“to“inspect“a“given“variable“in“any“candidateŽ¡‘0//–ffwhich“is“an“instance“of,“or“inherits“from,“a“given“classŽ¡‘0//Ž¡‘0@protocol–ffVarProbe“Ž¡‘0CREATINGŽ¡‘0-–ffsetProbedVariable:“(const“char“*)aVariable;Ž¡‘0SETTINGŽ¡‘0-–ffsetStringReturnType:“returnType;Ž¡‘0USINGŽ¡‘0-–ff(const“char“*)getProbedVariable;Ž¡‘0-–ffsetFloatFormat:“(const“char“*)format;Ž¡‘0//–ffCurrently,“setNonInteractive“must“be“used“*after*“create“phaseŽ¡‘0//–ffIn“any“case“these“should“also“become“setInteractive:“BOOL“etc.Ž¡¡‘0-‘ffsetNonInteractive;Ž¡‘0-‘ff(int)isInteractive;Ž¡¡‘0-–ff(void“*)probeRaw:“anObject;Ž¡‘0-–ff(void“*)probeAsPointer:“anObject;Ž¡‘0-–ff(int)probeAsInt:“anObject;Ž¡‘0-–ff(double)probeAsDouble:“anObject;Ž¡‘0-–ff(const“char“*)probeAsString:“anObject“Buffer:“(char“*)buffer;Ž¡‘0-–ff(const“char“*)probeAsString:“(id)“anObject“Buffer:“(char“*)buf“withFullPre-ŽŸ‘0cision:‘ff(int)precision;Ž¡‘0-–ffsetData:“anObject“To:“(void“*)“newValue;“//“pass“by“reference.Ž¡‘0-–ff(int)setData:“anObject“ToString:“(const“char“*)s;Ž¡‘0@endŽŸ‘0„¤ŽŽŸ†¿This–?ýis“a“specialized“subclass“of“the“abstract“class“ïhtml:ï html:¾Probe‘¼r¿.‘ úIt“completes“the“specificationŽ¤¼jof–?ýa“probe“whose“referent“is“an“instance“variable“element“of“an“object.ŽŸ€’ïhtml:ï html:ŸÕ¢ÀCrš°geate–QëPhase“Pr˜otocolŽŸ ¢Âïhtml:ï html:ŸÉù¿-–?ýsetProbedVariable:‘ ú(const“char“*)aVariable“sets“the“variable“being“probed“(elsewhere“calledŽ¡the–?ýreferent).‘ úThe“ïhtml:ï html:¾aVariable‘üo¿identifier“is“simply“a“character“string“consisting“of“the“identifierŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ìã “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿of–?ýthe“variable“referent.‘ úFor“example,“if“we“were“probing“a“variable“called“ïhtml:ï html:¾unhappiness‘¼r¿,ŽŸ¼jºâthen–?ýthe“string“would“be“"unhappiness".‘ úThis“method“ïhtml:ï html:must“be“called“during“the“create“phase.Žºâ¤€’ïhtml:ï html:©ÀSet–QëPhase“Pr°gotocolŽŸ ¢Âïhtml:ï html:Ÿ¡m¿-–?ýsetStringReturnType:‘ úreturnType“sets“the“format“that“will“be“used“to“print“the“variable.Ž¡ïhtml:ï html:¦ÀUsage‘QëPr°gotocolŽŸ âcïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿ¥b‘:¿-–?ýsetFloatFormat:‘ ú(const“char“*)ŽŸÕSïhtml:ï html:ŸT=‘XGiven–?ýan“sprintf“style“formatting“string“(eg.‘ ú"ïhtml:ï html:Â%.3f"¿)“to“a“floating-pointŽ¤‘X(or–?ýdouble-floating-point)“probe“will“use“this“formatting“ïhtml:ï html:¾only‘üo¿when“probingŽ¡‘Xon–?ýa“GUI“display“widget.‘ úSee“section“on“ïhtml:ï html:probing“precisionïhtml:ï html:Ž¤)‘X(../probing.html#precision)Ž¡‘Xwhen–?ýprobing“floating“point“number“in“the“documentation“on“probes.Ž¤8äïhtml:ï html:ïhtml:ï html:© ð¬‘:-‘?ýsetSafetyŽ¡ïhtml:ï html:ïhtml:ï html:¦‘:-‘?ýunsetSafetyŽŸ8äïhtml:ï html:¦‘XIn–?ýorder“to“ensure“efficiency,“the“default“behaviour“of“the“ïhtml:ï html:¾VarProbe‘üo¿is“toŽ¤‘X"trust"–?ýthat“the“object“it“is“being“presented“with“is“of“an“appropriate“classŽ¡‘X(the–?ýone“specified“in“ïhtml:ï html:¾setProbedClass‘¼r¿,“or“a“subclass“of“it).‘ úHowever,“by“callingŽ¡‘Xïhtml:ï html:¾setSafety‘¼r¿,–?ýwe“force“the“probe“to“inspect“the“class“of“the“target“object“beforeŽ¡‘Xprobing‘?ýit.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:-‘?ýsetNonInteractiveŽŸïhtml:ï html:ïhtml:ï html:Ÿ)‘:-‘?ý(int)isInteractiveŽŸÕSïhtml:ï html:ŸT=‘XBy–?ýsetting“a“ïhtml:ï html:¾VarProbe‘üo¿to“be“non-interactive“we“ensure“that“the“user“will“notŽ¡‘Xbe–?ýable“to“ïhtml:ï html:change“the“value“of“the“probe,“but“only“observe“it.‘ úThe“defaultŽ¡‘Xis–?ýfor“variables“of“type“ïhtml:ï html:Â(char–ff*),“char,“unsigned“char,“int,“unsigned“int,Ž¡‘Xfloat¿and–?ýïhtml:ï html:Âdouble“¿to“be“interactive“and“for“all“the“others“to“be“non-interactiveŽ¡‘X(with–?ýthe“exception“of“the“ïhtml:ï html:Âid“¿type“this“follows“because“there“is“no“simpleŽ¡‘Xway–?ýto“set“such“things“as“structs“or“arrays“by“typing“values“into“an“entryŽ¡‘Xfield).‘ úFor–?ýthe“time“being,“setting“the“VarProbe“to“be“non-interactive“willŽ¡‘Xnot–?ýinterfere“with“the“drag&drop“capability“of“objects“into“the“ïhtml:ï html:¾VarProbe‘üo¿entry-field...Ž¡‘XThis–?ýis“considered“an“omission“and“will“be“corrected“by“the“next“release.Ž¡‘XAlso,–?ýfor“the“time“being“there“is“no“way“to“disable“a“ïhtml:ï html:¾VarProbe‘üo¿once“it“hasŽ¡‘Xbeen–?ýdisplayed“(i.e.‘ úafter“a“ïhtml:ï html:¾ProbeDisplay›üo¿containing“the“ïhtml:ï html:¾VarProbe˜¿has“beenŽ¡‘Xcreated).‘ úThe–?ýability“to“do“this“will“also“be“included“in“the“next“release.Ž¤8äïhtml:ï html:ïhtml:ï html:¦‘:-–?ý(const“char“*)getProbedVariableŽŸ8äïhtml:ï html:¦‘Xreturns–?ýa“string“matching“the“identifier“of“the“referent.Ž¡ïhtml:ï html:ïhtml:ï html:¦‘:-‘?ý(int)getDataOffsetŽŸ8äïhtml:ï html:¦‘XThis–?ýis“another“example“of“a“method“used(?)‘ úexclusively“by“the“Swarm“kernel,ŽŸ‘Xit–?ýreturns“the“offset“used“to“extract“the“variable“from“the“target“object.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Íë “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ïhtml:ï html:Ÿ ‘:¿-–?ý(void“*)probeRaw:‘ úanObjectŽ¤8äïhtml:ï html:ïhtml:ï html:© à¶‘:-–?ý(void“*)probeAsPointer:‘ úanObjectŽ¡ïhtml:ï html:ïhtml:ï html:¦‘:-‘?ý(int)probeAsInt:‘ úanObjectŽ¡ïhtml:ï html:ïhtml:ï html:¦‘:-‘?ý(double)probeAsDouble:‘ úanObjectŽ¡ïhtml:ï html:ïhtml:ï html:¦‘:-–?ý(const“char“*)probeAsString:› úanObject“Buffer:˜(char“*)“bufferŽ¡ïhtml:ï html:ïhtml:ï html:¦‘:-–?ý(const“char“*)probeAsString:› úanObject“Buffer:˜(char“*)“buffer“withPrecision:Ž¤‘D(int)‘?ýprecisionŽŸ8äïhtml:ï html:¦‘XThese–?ýare“the“methods“which“actually“use“the“probe.‘ úïhtml:ï html:¾probeRaw‘üo¿simply“returnsŽ¡‘Xa–?ýpointer“to“the“probed“variable,“whereas“the“other“methods“return“it“as“aŽ¡‘Xparticular–?ýtype.‘ úïhtml:ï html:¾probeAsString‘üo¿simply“prints“the“value“of“the“variable“intoŽ¡‘Xthe–?ýbuffer“(in“more“or“less“the“same“format“you“would“expect“from“a“ïhtml:ï html:¾sprintf()‘¼r¿).Ž¡‘XThe–?ýbuffer“should“be“pre-allocated.‘ úThe“second“form“of“ïhtml:ï html:¾probeAsString‘üo¿is“onlyŽ¡‘Xused–?ýinternally“by“ïhtml:ï html:ïhtml:ï html:ÂObjectSaverïhtml:ï html:Ž¤ š‘X(../simtools/ObjectSaver.html)Ž¡‘X¿to–?ýuse“the“"saved“as"“precision“form“which“can“be“different“from“the“"displayed"Ž©‘Xprecision.‘ úSee–?ýthe“section“on“setting“the“ïhtml:ï html:probing“precisionïhtml:ï html:Ž¡‘X(../probing.html#precision)Ž¡‘Xfor–?ýfloating-point“numbers.– úïhtml:ï html:Note:“The–?ýïhtml:ï html:¾VarProbe‘üo¿will“complain“if“you“tryŽ¦‘Xto–?ýdo“weird“type“conversions:‘ úfor“example,“if“the“probed“variable“is“of“typeŽ¦‘Xpointer–?ýand“you“try“to“use“the“ïhtml:ï html:¾probeAsDouble‘üo¿method“then“the“return“valueŽ¦‘Xwill–?ýbe“undefined“(and“you“will“get“an“error“message“on“ïhtml:ï html:¾stderr‘¼r¿).ŽŸ8äïhtml:ï html:ïhtml:ï html:¤ à¶‘:-‘?ýsetStringReturnType:‘ úreturnTypeŽŸ8äïhtml:ï html:¡‘XWhen–?ýthe“ïhtml:ï html:¾probedVariable‘üo¿is“of“type“ïhtml:ï html:Âunsigned‘ffchar“¿or“ïhtml:ï html:Âchar¿,“the“method“ïhtml:ï html:¾probeAsStringŽ¦‘X¿will,–?ýby“default,“return“a“string“of“the“format:› ú"'%c'“%d".˜This“is“meantŽ¦‘Xto–?ýreflect“the“commonplace“use“of“an“ïhtml:ï html:Âunsigned‘ffchar“¿as“a“small“ïhtml:ï html:Âint¿.‘ úHowever,Ž¦‘Xthe–?ýuser“can“tailor“the“format“returned“by“the“probe“to“use“only“one“of“theŽ¦‘Xtwo–?ýpossible“representations.Ž©8äïhtml:ï html:¡‘0The–?ýlegal“values“for“returnType“are:Ž¦ïhtml:ï html:Ÿïhtml:ï html:¡‘Xïcolor push BlackÁlï color popŽŽ‘bïhtml:ï html:¿DefaultString–?ý("'%c'“%i")Ž¦ïhtml:ï html:¡‘Xïcolor push BlackÁlï color popŽŽ‘bïhtml:ï html:¿CharString‘?ý("'%c'")Ž¦ïhtml:ï html:¡‘Xïcolor push BlackÁlï color popŽŽ‘bïhtml:ï html:¿IntString‘?ý("%i").Ž¦ïhtml:ï html:¡‘XNote:‘ úWhen–?ýsetting“the“value“of“an“unsigned“char“or“a“char“using“the“ïhtml:ï html:¾setData:ToString:Ž¤‘X¿(method–?ýdescribed“below),“the“expected“format“of“the“string“is“always“"%i"Ž¡‘Xunless–?ýïhtml:ï html:¾CharString‘üo¿was“chosen“(in“which“case“the“format“should“be“"'%c'").Ž¦ïhtml:ï html:ïhtml:ï html:¤ à¶‘:-–?ýsetData:› úanObject“To:˜(void“*)newValueŽ¦ïhtml:ï html:ïhtml:ï html:¡‘:-–?ýsetData:› úanObject“ToString:˜(const“char“*)sŽŸ8äïhtml:ï html:¡‘XThe–?ýprogrammer“can“set“the“ïhtml:ï html:¾probedVariable‘üo¿via“these“methods,“either“by“providingŽ¤‘Xa–?ýpointer“to“the“new“value“or“a“string“which“the“probe“will“read“and“convertŽ¡‘Xappropriately.– úïhtml:ï html:Note:“For–?ýthe“time“being,“the“kernel“itself“is“the“only“softwareŽ¡‘Xwhich–?ýuses“probes“in“this“fashion,“so“we“can“get“away“with“expecting“eitherŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Îü “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Wºâ¿a–?ýstring“or“a“pointer.‘ úHowever,“if“any“user“should“require“more“types“(suchŽ¤‘Wºâas–?ýthe“choice“provided“in“the“ïhtml:ï html:¾probeAs‘üo¿series),“please“ïhtml:ï html:emailïhtml:ï html:Ž¡‘Wºâ(mailto:swarm@santafe.edu)Ž¡‘Wºâus–?ýand“I“will“include“them“in“the“following“release!Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(Probe.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRïï html:¦(SwarmObject.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(MessageProbe.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ïø “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½MessagePr |obe‘/ClassŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤Î‘0Â//Ž¡‘0//–ffMessageProbe“--Ž¡‘0//‘32Allows–ffthe“user“to“call“a“given“message“on“any“candidateŽ¡‘0//‘32which–ffis“an“instance“of,“or“inherits“from,“a“given“classŽ¡‘0//Ž¡‘0@protocol–ffMessageProbe“Ž¡‘0CREATINGŽ¡‘0-–ffsetProbedSelector:“(SEL)“aSel;Ž¡‘0-–ffsetProbedMessage:“(const“char“*)aMessage;Ž¡‘0-–ffsetHideResult:“(int)“val;Ž¡‘0USINGŽ¡‘0-(int)isResultId;‘[ÌÆ//–ffI“doubt“that“a“user“willŽ¡‘0-(int)isArgumentId:–ff(int)which;‘32//“ever“need“these.Ž¡¡‘0-–ff(const“char“*)getProbedMessage;Ž¡‘0-‘ff(int)getArgNum;Ž¡‘0-–ff(const“char“*)getArg:“(int)which;Ž¡‘0-–ff(const“char“*)getArgName:“(int)which;Ž¡‘0-‘ff(int)getHideResult;Ž¡¡‘0-–ffsetArg:“(int)which“To:“(const“char“*)what;Ž¡¡‘0-–ffdynamicCallOn:“target“resultStorage:“(const“char“**)result;Ž¡‘0-–ffdynamicCallOn:“target;Ž¡¡‘0-–ffupdateMethodCache:“anObject;Ž¡‘0-–ff(int)intDynamicCallOn:“target;Ž¡‘0-–ff(float)floatDynamicCallOn:“target;Ž¡‘0-–ff(double)doubleDynamicCallOn:“target;Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¿This–?ýis“a“specialized“subclass“of“the“abstract“class“ïhtml:ï html:Probe.‘ úIt“completes“the“specificationŽŸ‘0of–?ýa“probe“whose“referent“is“a“message“element“of“an“object.ŽŸ€’ïhtml:ï html:ŸžTÀCrš°geate–QëPhase“Pr˜otocolŽŸ ¢Âïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:ŸÖA‘:¿setProbedSelector:‘ ú(SEL)aSelectorŽŸÕSïhtml:ï html:ïhtml:ï html:ŸE{‘:setProbedMessage:‘ ú(const–?ýchar“*)aMessageŽŸ8äïhtml:ï html:Ÿ áê‘Xsets–?ýthe“message“to“be“probed.‘ úAt“least“one“of“these“methods“ïhtml:ï html:must“be“called.ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÐB “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿Note–?ýthat“due“to“a“bug“in“gcc-2.7.2“it“is“unadvisable“(though“we“have“not“disallowedŽ¤‘/ºâit)–?ýto“make“a“message“probe“using“ïhtml:ï html:setProbedMessage.‘ úThe“next“release“of“gcc“willŽ¡‘/ºâcontain–?ýa“patch“for“this“bug.‘ úIf“you“absolutely“require“the“ability“to“create“messageprobesŽ¡‘/ºâusing–?ýïhtml:ï html:setProbedMessage,“please“ïhtml:ï html:emailïhtml:ï html:Ž¤AZ‘/ºâ(mailto:‘ úswarm@santafe.edu)Ž¡‘/ºâus.ŽºâŸG®ïhtml:ï html:ŸýÄÀUsage‘QëPr°gotocolŽŸ âcïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿ½,‘:¿(const–?ýchar“*)getProbedMessageŽ©8äïhtml:ï html:¤ v‘Xreturns–?ýthe“string“matching“the“identifier“of“the“message“being“probed.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:(int)getHideResultŽ¦ïhtml:ï html:ïhtml:ï html:¡‘XsetHideResult:‘ ú(int)val–?ýBy“setting“ïhtml:ï html:hideResult“to“1,“the“user“is“indicatingŽ¤‘Xthat–?ýthe“result“field,“in“a“graphical“representation“of“the“message“probe,Ž¡‘Xshould–?ýnot“be“shown.‘ úIn“other“words,“if“a“probe“display“attempts“to“representŽ¡‘Xthe–?ýmessage“probe,“it“should“hide“the“result“window.‘ úThis“is“useful,“particularlyŽ¡‘Xwhen–?ýthe“return“value“is“defined“to“be“self.ŽŸïhtml:ï html:ïhtml:ï html:ŸAZ‘:(const–?ýchar“*)getArg:‘ ú(int)whichŽ¦ïhtml:ï html:¤ v‘Xreturns–?ýa“string“representation“of“the“n'th“argument.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:(int)getArgNumŽ¦ïhtml:ï html:¡‘Xreturns–?ýthe“number“of“arguments“the“message“takes.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:(const–?ýchar“*)getArgName:‘ ú(int)whichŽ¦ïhtml:ï html:¡‘Xreturns–?ýa“string“representation“of“the“argument“with“the“given“name.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:setArg:– ú(int)which›?ýTo:“(const˜char˜*)whatŽ¦ïhtml:ï html:¡‘Xsets–?ýthe“n'th“argument“of“the“message“-“the“argument“must“be“provided“in“stringŽ¤‘Xform.ŽŸïhtml:ï html:ïhtml:ï html:ŸAZ‘:(int)isResultIdŽŸÕSïhtml:ï html:Ÿl‘XThis–?ýmethod“is“used“by“the“Swarm“internals“to“find“out“whether“the“returnŽ¡‘Xvalue–?ýof“the“message“is“of“type“object.ŽŸ8äïhtml:ï html:ïhtml:ï html:¤ v‘:(int)isArgumentId:‘ ú(int)whichŽ¦ïhtml:ï html:¡‘XThis–?ýmethod“is“used“by“the“Swarm“internals“to“find“out“whether“a“given“argumentŽŸ‘Xof–?ýthe“message“is“of“type“object.ŽŸ8äïhtml:ï html:ïhtml:ï html:¡‘:updateMethodCache:‘ úanObjectŽ¦ïhtml:ï html:¡‘XThe–?ýmessage“probe“will“always“attempt“to“optimise“the“way“in“which“it“dispatchesŽ¤‘Xdynamic–?ýcalls“to“the“probed“objects.‘ úIn“practice,“this“means“that“when“theŽ¡‘Xprobed–?ýmessage“takes“no“arguments,“then“the“message“probe“will“cache“the“actualŽ¡‘Ximplementation–?ýof“the“method“and“generate“direct“C“function“calls“(as“opposedŽ¡‘Xto–?ýcalling“ïhtml:ï html:perform,“for“example)“ïhtml:ï html:if“the“user“promises“that“only“one“classŽ¡‘Xof–?ýobjects“is“being“probed.‘ úThe“user“does“this“by“calling“the“ïhtml:ï html:updateMethodCache:Ž¡‘Xwith–?ýan“example“object“of“the“appropriate“target“class.‘ úThis“method“can“beŽ¡‘Xcalled–?ýas“often“as“necessary“throughout“the“lifetime“of“the“message“probe.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ v‘:dynamicCallOn:‘ útargetŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÑÀ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ïhtml:ï html:Ÿ ‘:¿dynamicCallOn:– útarget›?ýresultStorage:“(const˜char˜**)resultŽ¤8äïhtml:ï html:ïhtml:ï html:© Ç‘:(int)intDynamicCallOn:‘ útargetŽ¡ïhtml:ï html:ïhtml:ï html:¦‘:(double)doubleDynamicCallOn:‘ útargetŽŸ8äïhtml:ï html:¦‘XThese–?ýare“the“methods“used“to“actually“generate“a“dynamic“message“call“onŽ¤‘Xthe–?ýtarget“object.‘ úThe“first“method“does“not“return“a“result,“the“secondŽ¡‘Xwill–?ýreturn“a“dynamically“ïhtml:ï html:malloc'ed“string“based“representation“of“the“result,Ž¡‘Xwhereas–?ýthe“third“and“fourth“methods“assume“the“user“knows“the“exact“typingŽ¡‘Xof–?ýthe“method“and“would“like“a“direct“translation“into“the“appropriate“datatype.Ž©‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(VarProbe.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRïï html:¦(SwarmObject.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(ProbeMap.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ò,² “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½CustomPr |obeMap‘/ClassŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤=V‘0Â//Ž¡‘0//–ffCustomProbeMap“--Ž¡‘0//‘32A–ffsubclass“of“ProbeMap,“whose“initial“state“is“empty“unlike“the“defaultŽ¡‘0//‘32probeMap–ffinitial“state“which“contains“all“the“VarProbesŽ¡‘0//‘32of–ffthe“requested“target“class.Ž¡‘0//Ž¡‘0@protocol–ffCustomProbeMap“Ž¡‘0+–ffcreate:“aZone“forClass:“(Class)aClass“withIdenti-ŽŸ‘0fiers:–ff(const“char“*)vars,“...;Ž¡‘0@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¿This–?ýsubclass“of“the“ïhtml:ï html:ProbeMap“is“used“to“create“probe“maps“which“are“initialised“inŽ¤‘0an–?ýemtpy“state“or“with“the“ïhtml:ï html:VarProbes“and“ïhtml:ï html:MessageProbes“intended.‘ úIn“other“words,Ž¡‘0the–?ýprobed“class“is“set,“as“is“the“case“with“the“normal“ïhtml:ï html:ProbeMap“class“but“upon“ïhtml:ï html:createEndŽ¡‘0no–?ýïhtml:ï html:VarProbes“or“ïhtml:ï html:MessageProbes“will“be“present“within“it.‘ úThis“feature“is“useful“whenŽ¡‘0creating–?ýa“probe“map“from“scratch“(e.g.‘ úto“be“used“in“conjunction“with“the“ïhtml:ï html:setProbeMap:For:Ž¡‘0message–?ýof“the“ïhtml:ï html:ProbeLibrary).Ž©8äïhtml:ï html:Ÿ r‘0An–?ýadditional“convenience“method“was“added“to“help“compress“the“amount“of“code“neededŽ¡‘0to–?ýcreate“a“custom“probe.Ž¦ïhtml:ï html:ïhtml:ï html:Ÿ r‘0É+–ffcreate:“aZone“forClass:“(Class)aClass“withIdenti-Ž¡‘0fiers:–ff(const“char“*)vars,“...;ŽŸõ]ïhtml:ï html:ŸGù‘0¿This–?ýis“a“variable“argument“message“which“takes“a“Zone,“a“Class“name,“and“a“colon-delimitedŽ¡‘0list–?ýof“instance“variable“names“and“message“names“valid“for“that“class.‘ úThe“instanceŽ¡‘0variable–?ýidentifiers“are“listed“first“followed“by“a“string“consisting“solely“of“aŽ¡‘0":"–?ýfollowed“by“the“message“identifiers.‘ úThe“general“format“would“be:Ž¦ïhtml:ï html:Ÿ r‘0Â[CustomProbeMap–ffcreate:“aZoneŽ¤=V‘{™”forClass:‘ffaClassŽ¡‘UÌÊwithIdentifiers:–ff"variable1",“"variable2",“...,Ž¡’±™":",Ž¡’±™"message1",–ff"message2",“...,Ž¡’±™NULL];Ž¡¿All–?ýstrings“up“to“the“":"“are“read“as“instance“variable“names“and“placed“in“the“probe“map“andŽ¤all–?ýstrings“after“the“":"“are“read“as“message“names“and“placed“in“the“probe“map.‘ úThe“NULLŽ¡string–?ýterminates“the“list.‘ úAn“example“of“this“message“being“used“is“given“in“the“ïhtml:ï html:AdvancedŽ¡Usage‘?ýGuideïhtml:ï html:Ž¤=V(./AdvancedUsage.html)Ž¡.ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ó3â “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÖ\’á³4ï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽºâ¤ ïhtml:ï html:©¿(ProbeMap.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(CompleteProbeMap.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ô?Í “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½CompletePr |obeMap‘/ClassŽŸq'‘0„¤ŽŽ© ïhtml:ï html:¤‘0Â//Ž¡‘0//–ffCompleteProbeMap“--Ž¡‘0//‘32A–ffsubclass“of“ProbeMap,“whose“initial“state“contains“the“VarProbes“andŽ¡‘0//‘32MessageProbes–ffof“the“requested“target“class“but“also“those“of“all“itsŽ¡‘0//‘32superclasses.Ž¡‘0//Ž¡‘0@protocol–ffCompleteProbeMap““@endŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¿Upon–?ýcreation,“this“subclass“of“the“ïhtml:ï html:ProbeMap“will“contain“all“the“variables“and“allŽ¡‘0the–?ýmessages“of“a“given“class“(including“the“inherited“ones).Ž¤‘0„¤ŽŽ¦ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¦ïhtml:ï html:¡(EmptyProbeMap.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¡(Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¦ïhtml:ï html:¡(CompleteVarMap.html)Ž¡‘0„¤ŽŽ¦ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÕCy “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Objectbase–/Library:‘m™Usage“GuideŽŸq'‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ5YÀOv•ÓÅer“viewŽŸ ¢Âïhtml:ï html:Ÿ4b‘0¿The–?ýïhtml:ï html:objectbase“library“contains“the“most“basic“objects“users“need“to“design“theirŽ¤‘0agents–?ýand“swarms.‘ úIt“also“serves,“at“present,“as“a“repository“for“the“probe“machinery,Ž¡‘0which–?ýis“provided“for“every“ïhtml:ï html:SwarmObject.‘ úThe“way“the“classes“in“this“library“areŽ¡‘0to–?ýbe“used“is“varied.‘ úBut,“basically,“it“is“provided“so“that“the“user“will“have“somethingŽ¡‘0to–?ýsubclass“from“for“her“own“objects“and“Swarms.ŽŸ€’ïhtml:ï html:ŸüuÀExample–QëUsage“of“ïhtml:ï html:SwarmObjectŽŸ âcïhtml:ï html:ŸôÁ‘0¿The–?ýbest“way“to“explain“how“the“library“should“be“used“is“to“walk“through“an“example.Ž¡‘0So,–?ýusing“Heatbugs,“we'll“walk“through“the“ways“ïhtml:ï html:objectbase“is“used“and“discuss“them.Ž¡‘0Since–?ýmore“documentation“is“usually“better“than“less,“I'm“going“to“explain“thingsŽ¡‘0at–?ýa“low“level“so“that“those“not“familiar“with“Objective“C“will“understand“the“discussion.Ž¡‘0If–?ýyou“already“are“familiar“with“Objective“C,“then“you“should“skip“this“part.Ž©8äïhtml:ï html:Ÿ @‘0First–?ýoff,“the“basic“elements“of“the“Heatbugs“simulation“are“the“heatbugs,“the“modelŽ¡‘0swarm–?ý(which“bundles“the“heatbugs),“and“the“observer“swarm“(which“bundles“the“displaysŽ¡‘0of–?ýthe“probes“poking“into“the“model“swarm“and“the“heatbugs).‘ úThe“interface“filesŽ¡‘0for–?ýeach“show“what“must“be“imported“and“the“declaration“syntax“needed“to“subclassŽ¡‘0from‘?ýïhtml:ï html:SwarmObject.Ž¦ïhtml:ï html:Ÿ @‘0We'll–?ýuse“ïhtml:ï html:ÂHeatbug.h“¿for“our“discussion“here.‘ úThe“first“part“of“the“file“shows“theŽ¡‘0C-preprocessor–?ýimports“needed:Ž¦ïhtml:ï html:Ÿ @‘0Â#import‘ffŽ¤xï‘0#import‘ffŽ¡‘0#import‘ff"HeatSpace.h"Ž¡‘0#import‘ffŽŸbÌïhtml:ï html:Ÿ#‘0¿The–?ýïhtml:ï html:Â#import‘ff;“¿is“included“in“order“to“subclass“from“ïhtml:ï html:SwarmObject.Ž¤‘0However,–?ýto“provide“backwards“compatibility,“we've“placed“this“import“in“the“libraryŽ¡‘0interface–?ýfile“ïhtml:ï html:Âobjectbase.h“¿as“well,“which“means“one“could“subclass“from“ïhtml:ï html:SwarmObjectŽ¡‘0by–?ýsimply“importing“the“ïhtml:ï html:Âobjectbase.h“¿file.‘ úThis“is“discouraged“in“order“to“makeŽ¡‘0the–?ýlibrary“interfaces“as“standard“as“possible.Ž¦ïhtml:ï html:¤ @‘0The–?ýnext“ïhtml:ï html:objectbase“relevant“piece“of“code“in“this“file“is:Ž¦ïhtml:ï html:¡‘0Â@interface–ffHeatbug:“SwarmObjectŽ¤xï‘0ÇfŽ¡‘:ÌÌÂdouble‘ffunhappiness;Ž¡‘:ÌÌint–ffx,“y;Ž¡‘:ÌÌHeatValue‘ffidealTemperature;Ž¡‘:ÌÌHeatValue‘ffoutputHeat;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÖIø “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘:‡®Âfloat‘ffrandomMoveProbability;Ž¤ %¡‘:‡®Grid2d–ff*“world;Ž¡‘:‡®int–ffworldXSize,“worldYSize;Ž¡‘:‡®HeatSpace–ff*“heat;Ž¡‘:‡®Color‘ffbugColor;Ž¡‘/ºâÇgŽºâŸ@ïhtml:ï html:Ÿ å‘0¿The–?ýïhtml:ï html:Â@interface“¿keyword“indicates“that“you“are“beginning“the“definition“of“the“partŽ¤‘0of–?ýan“object“(a“ïhtml:ï html:Heatbug“in“this“case)“that“will“be“visible“to“other“objects.‘ úTheŽ¡‘0ïhtml:ï html:ÂHeatbug:‘ ÌÌSwarmObject–?ý¿indicates“that“you“are“calling“this“object“ïhtml:ï html:Heatbug“and“it“isŽ¡‘0a–?ýsubclass“of“ïhtml:ï html:SwarmObject.‘ úWhat“follows“between“the“curly“braces“(¸fg¿)“are“the“instanceŽ¡‘0variables–?ýdefined“for“the“ïhtml:ï html:Heatbug“class“ïhtml:ï html:above“and“beyond“those“inherited“from“theŽ¡‘0ïhtml:ï html:SwarmObject‘?ýclass.Ž©8äïhtml:ï html:Ÿ ì¬‘0Inside–?ýthis“"agent,"“we“have“defined“several“parameters“associated“with“either“theŽ¡‘0agent,–?ýitself,“or“the“space“in“which“it“sits.‘ úAny“data“that“will“need“to“be“presentŽ¡‘0throughout–?ýall“the“behavior“and“lifetime“of“the“agent“should“be“declared“here.‘ úAlso,Ž¡‘0anything–?ýdeclared“here“will“be“accessible“to“the“probe“machinery,“and“so“will“be“capableŽ¡‘0of–?ýbeing“manipulated“and“viewed“from“outside“the“agent.Ž¦ïhtml:ï html:Ÿ ì¬‘0Next–?ýcome“the“message“prototypes“to“which“this“agent“will“respond.‘ úAnd“it“is“worthŽ¡‘0noting–?ýagain“that“these“are“ïhtml:ï html:in“addition“to“those“declared“in“the“ïhtml:ï html:SwarmObject“superclass.Ž¡‘0So,–?ýnot“only“will“other“objects“be“able“to“send“messages“to“this“agent“that“are“declaredŽ¡‘0here,–?ýbut“other“objects“will“be“able“to“send“all“the“messages“declared“in“the“ïhtml:ï html:Âob-Ž¡‘0jectbase/SwarmObject.h–?ý¿imported“previously.‘ úThe“messages“prototyped“here“will“dictateŽ¡‘0what–?ýthe“compiler“thinks“this“object“can“respond“to.‘ úHence,“if“any“part“of“any“ofŽ¡‘0these–?ýprototypes“differs“from“the“corresponding“function“definition“in“the“ïhtml:ï html:ÂHeat-Ž¡‘0bug.m–?ý¿file,“then“the“compiler“will“say“something“like“ïhtml:ï html:ÂObject:‘ ÌÌaHeatbug–ffdoes“notŽ¡‘0respond–ffto“xyz¿,–?ýwhere“"xyz"“is“the“name“of“the“message“that“is“being“sent“to“theŽ¡‘0ïhtml:ï html:ÂHeatbug¿.‘ úA–?ýscript“is“provided“with“the“Swarm“distribution“that“fixes“header“fileŽ¡‘0prototypes–?ýto“match“the“message“declarations“in“the“corresponding“".m"“file.‘ úThisŽ¡‘0script–?ýshould“be“in“the“ïhtml:ï html:Â$SWARMHOME/bin“¿directory“and“is“called“ïhtml:ï html:Âm2h¿.Ž¦ïhtml:ï html:Ÿ ì¬‘0One–?ýmore“thing“to“notice“about“these“prototypes“is“that“some“of“them“are“duplicatesŽ¡‘0of–?ýwhat“appears“in“the“ïhtml:ï html:Âobjectbase/SwarmObject.h“¿file.‘ úThis“means“that“when“the“messageŽ¡‘0is–?ýcalled“on“a“ïhtml:ï html:Heatbug“object,“it“will“execute“the“method“defined“here“and“not“theŽ¡‘0one–?ýin“the“ïhtml:ï html:SwarmObject“class.‘ úIn“the“ïhtml:ï html:objectbase“library,“the“following“messages“areŽ¡‘0intended–?ýto“be“overridden,“as“necessry:‘ úïhtml:ï html:Âcreate:,–ffcreateBegin:,“createEnd,“cus-Ž¡‘0tomizeBegin:,–ffcustomizeEnd,“customizeCopy:,“describe:,“and“getInstanceName.‘ ú¿EachŽ¡‘0of–?ýthese“messages“do“specific“things“that“may“change“from“subclass“to“subclass“ofŽ¡‘0ïhtml:ï html:SwarmObject.› úIn–?ýthis“case,“however,“we're“only“overriding“ïhtml:ï html:ÂcreateEnd¿.˜The“differencesŽ¡‘0between–?ýwe“implement“it“in“ïhtml:ï html:Heatbugs“and“the“default“is“not“that“significant.‘ úBut,Ž¡‘0it–?ýshould“be“pointed“out“that“when“overriding“certain“messages,“like“ïhtml:ï html:ÂcreateBegin:Ž¡‘0¿and–?ýïhtml:ï html:ÂcreateEnd¿,“the“new“method“should“call“the“superclass'“version“of“the“message,Ž¡‘0as–?ýwell.‘ úThis“is“done“using“the“default“pointer“to“the“superclass,“designated“ïhtml:ï html:super.Ž¡‘0The–?ýsyntax“in“the“ïhtml:ï html:Heatbugs“case“is:Ž¦ïhtml:ï html:Ÿ ì¬‘0Â[super‘ffcreateEnd];ŽŸbÌïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹×W! “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿The–?ýreasons“for“doing“this“are“related“to“the“object“phase“protocols“used“by“ïhtml:ï html:defobj.Ž©‘/ºâIf–?ýyou“would“like“more“info“on“that,“see“ïhtml:ï html:Objective“C“-“Swarm“Styleïhtml:ï html:Ž¤® ‘/ºâ(../../swarmObjC.html)Ž¡‘/ºâin–?ýthe“section“entitled“ïhtml:ï html:¾The“Create“Phase“In“Principle‘¼r¿.Žºâ¤8äïhtml:ï html:Ÿ u¼‘0Finally,–?ýthe“ïhtml:ï html:Â@end“¿keyword“signifies“the“end“of“the“interface“definition.‘ úGNU“ObjectiveŽ¦‘0C–?ýallows“one“to“leave“this“off;“but,“it“is“not“good“practice.Ž¡ïhtml:ï html:Ÿ u¼‘0And–?ýthat's“it.‘ úOf“course,“there're“a“few“tricky“aspects“to“using“the“ïhtml:ï html:objectbase“libraryŽ¦‘0that–?ýweren't“mentioned“here.‘ úSome“of“them“will“be“mentioned“in“the“ïhtml:ï html:Advanced“UsageŽ¦‘0Notesïhtml:ï html:Ž¤® ‘0(AdvancedUsage.html)Ž¡‘0and–?ýthe“ïhtml:ï html:Implementation“Notesïhtml:ï html:Ž¡‘0(Implementation.html)Ž¡‘0;–?ýbut,“the“best“way“to“learn“is“to“examine“the“way“the“demo“applications“do“it“andŽ¦‘0try–?ýto“make“some“changes“yourself.Ž¤‘0„¤ŽŽ©G®ïhtml:ï html:Ÿk ÀSubclassing–Qëfr°gom“ïhtml:ï html:SwarmŽŸ âcïhtml:ï html:Ÿ *r‘0¿Subclassing–?ýfrom“the“ïhtml:ï html:Swarm“class“works“very“similar“to“subclassing“from“ïhtml:ï html:SwarmObject.Ž¡‘0„¤ŽŽ¦ïhtml:ï html:Ÿk ÀActiÓÅvityContr°golŽŸ âcïhtml:ï html:Ÿ *r‘0¿The–?ýïhtml:ï html:ActivityControl“object“provides“much“more“finely“grained“control“over“the“executionŽ¤‘0of–?ýan“interactive“simulation.‘ úIt“addresses“both“the“problems“of“not“being“able“toŽ¡‘0stop–?ýthe“simulation“at“any“given“point“in“any“given“activity“and“provides“an“initialŽ¡‘0step–?ýtowards“a“Swarm“debugger.ŽŸ8äïhtml:ï html:Ÿ u¼‘0An–?ýactivity“controller“can“be“attached“to“ïhtml:ï html:any“activity“that“is“created“in“a“SwarmŽ¡‘0simulation,–?ýincluding“those“that“are“created“for“use“only“by“the“Swarm“kernel.‘ úTheŽ¡‘0controller–?ýthen“provides“the“basic“activity“manipulation“messages“on“that“activity,Ž¡‘0which›?ýare:‘ úïhtml:ï html:Ârun,–ffstop,“next,“step,“stepUntil,˜¿and˜ïhtml:ï html:Âterminate¿.ŽŸbÌïhtml:ï html:ŸKÔ‘0The–?ýpresence“of“the“ïhtml:ï html:ActivityControl“object“might“cause“some“confusion“about“what“roleŽ¡‘0the–?ýïhtml:ï html:ControlPanel“should“play“in“the“controlled“execution“of“the“various“schedules.Ž¡‘0The–?ýïhtml:ï html:ControlPanel“should“still“be“used“for“the“top-level“control“of“any“simulationŽ¡‘0that–?ýis“running“in“a“context“where“ïhtml:ï html:random“interference“is“expected“(like“under“a“GUISwarmŽ¡‘0where–?ýthe“user“may“click“a“button“at“any“time).‘ úThe“reason“this“is“true“is“becauseŽ¡‘0the–?ýïhtml:ï html:ControlPanel“sends“pseudo-interrupts“to“the“infinite“loop“we“use“to“perpetuateŽ¡‘0execution–?ýof“the“top“level“Swarm“(which“can“only“be“seen“in“the“form“of“the“ïhtml:ï html:Âgo“¿messageŽ¡‘0on–?ýa“ïhtml:ï html:GUISwarm“at“present).› úïhtml:ï html:This“type“of“control“may“change“in“the“future!˜But,“forŽ¡‘0now,–?ýit“is“how“we“monitor“the“control“state“of“the“simulation.ŽŸcïhtml:ï html:ŸK‘0Now,–?ýhaving“said“that,“the“ïhtml:ï html:ControlPanel“should“no“longer“be“used“to“run“the“simulation.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Øi¯ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿It–?ýshould“only“be“used“to“instantiate“the“control“context“and“quit“the“entire“simulation.Ž¤‘/ºâThat–?ýmeans“that“sometime“in“the“future,“the“ïhtml:ï html:ÂGo“¿and“the“ïhtml:ï html:ÂStop“¿buttons“will“be“removedŽ¡‘/ºâfrom–?ýthe“ïhtml:ï html:ControlPanel“display.‘ úThey“have“been“left“in“for“backwards“compatibilityŽ¡‘/ºâso–?ýthat“applications“that“do“not“use“the“new“ïhtml:ï html:ActivityControl“will“retain“their“(albeitŽ¡‘/ºâhandicapped)–?ýcontrollability.‘ úAlso,“the“current“ïhtml:ï html:ÂTime‘ffStep“¿button“will“be“renamedŽ¡‘/ºâto–?ýïhtml:ï html:ÂStart“¿to“be“consistent“with“it's“new“purpose.Žºâ©8äïhtml:ï html:Ÿ Ç‘0In–?ýorder“to“use“the“new“control“mechanism,“you“must“place“code“like“the“followingŽ¡‘0in–?ýthe“top-level“Swarm.‘ ú(This“code“was“taken“from“a“modified“mousetrap“demo“app.)Ž¦ïhtml:ï html:Ÿ Ç‘0ÂobserverActCont–ff=“[ActivityControl“createBegin:“[self“getZone]];Ž¡‘:ÌÌobserverActCont–ff=“[observerActCont“createEnd];Ž¡‘:ÌÌ[observerActCont–ffattachToActivity:“[self“getSwarmActivity]];Ž¡‘:ÌÌ[probeDisplayManager–ffcreateProbeDisplayFor:“observerActCont];ŽŸbÌïhtml:ï html:Ÿ 4‘0¿This–?ýcreates“an“ïhtml:ï html:ActivityControl“and“attaches“it“to“the“top-level“activity“(in“thisŽ¡‘0case–?ýan“ïhtml:ï html:ÂobserverSwarm¿).› úIt“also“creates“a“display“for“the“controller.˜(The“probeŽ¡‘0map–?ýfor“the“ïhtml:ï html:ActivityControl“class“is“designed“within“the“ïhtml:ï html:ActivityControl,“itself.Ž¡‘0This–?ýis“done“because“all“of“these“objects“are“expected“to“look“the“same“to“any“outsideŽ¡‘0object.)‘ úWith–?ýthis“activity“controller,“you“will“then“be“able“to“ïhtml:ï html:Ârun,–ffstop,“next,Ž¡‘0step,‘ffstepUntil,–?ý¿and“ïhtml:ï html:Âterminate“¿that“activity.Ž¦ïhtml:ï html:Ÿ Ç‘0There–?ýare“some“tricky“aspects“to“successfully“using“an“ïhtml:ï html:ActivityControl“object“thatŽ¡‘0the–?ýïhtml:ï html:Advanced“Usage“Notesïhtml:ï html:Ž¡‘0(AdvancedUsage.html)Ž¡‘0will‘?ýcover.ŽŸïhtml:ï html:©‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRïï html:¦(../objectbase.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(AdvancedUsage.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ùyt “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Objectbase–/Library:‘m™AdvÊìanced“Usage“NotesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:Ÿïhtml:ï html:©TÃ‘0ïcolor push Black¿1.ï color popŽŽ‘<ïhtml:ï html:ProbeMap–?ýdesign:‘ úWhen“designing“a“ïhtml:ï html:ProbeMap“for“a“given“(subclass“of)“ïhtml:ï html:SwarmObject,Ž¤‘<inclusion–?ýof“instance“variables“or“messages“defined“in“the“super“class“might“beŽ¡‘<desirable.‘ úThe–?ýnormal“ïhtml:ï html:ProbeMap“design“code“might“look“like“(this“code“was“takenŽ¡‘<from–?ýthe“tutorial“app“called“"hello-world"):ŽŸ8äïhtml:ï html:Ÿ ß‘$ÂprobeMap–ff=“[CustomProbeMap“createBegin:“[self“getZone]];Ž¦‘Dfd[probeMap–ffsetProbedClass:“[person“class]];Ž¦‘DfdprobeMap–ff=“[probeMap“createEnd];Ž¦‘Dfd[probeMap–ffaddProbe:“[probeLibrary“getProbeForVariable:“"room"Ž¦‘)ffinClass:–ff[person“class]]];Ž¦‘Dfd[probeMap–ffaddProbe:“[probeLibrary“getProbeForVariable:“"party"Ž¦‘)ffinClass:–ff[person“class]]];Ž¦‘Dfd[probeMap–ffaddProbe:“[probeLibrary“getProbeForVariable:“"name"Ž¦‘)ffinClass:–ff[person“class]]];Ž¦‘Dfd[probeMap–ffaddProbe:“[probeLibrary“getProbeForVariable:“"stillhere"Ž¦‘)ffinClass:–ff[person“class]]];Ž¦‘Dfd[probeMap–ffaddProbe:“[probeLibrary“getProbeForVariable:“"listOfFriends"Ž¦‘)ffinClass:–ff[person“class]]];Ž¦‘Dfd[probeMap–ffaddProbe:“[probeLibrary“getProbeForVariable:“"myColor"Ž¦‘)ffinClass:–ff[person“class]]];Ž¦‘Dfd[probeLibrary–ffsetProbeMap:“probeMap“For:“[person“class]];Ž¦‘Dfd[probeDisplayManager–ffcreateProbeDisplayFor:“person];ŽŸbÌïhtml:ï html:Ÿ ñ÷‘<¿where›?ýïhtml:ï html:Âroom,–ffparty,“name,“stillhere,“listOfFriends,˜¿and˜ïhtml:ï html:ÂmyColor˜¿are˜instance˜variablesŽ¡‘Hdeclared–?ýin“the“interface“to“the“ïhtml:ï html:Person“subclass.‘ úAnd“ïhtml:ï html:Person“is“a“subclass“ofŽ¡‘Hïhtml:ï html:Agent2d,–?ýwhich“is“a“subclass“of“ïhtml:ï html:SwarmObject.ŽŸ8äïhtml:ï html:Ÿ ß‘<Now–?ýlet's“say“that“there“are“two“variables“declared“in“ïhtml:ï html:Agent2d“that“you“want“toŽ¡‘Hput–?ýinto“this“custom“probe“in“addition“to“the“ones“you've“picked“out“of“ïhtml:ï html:Person.Ž¡‘HCall–?ýthem“ïhtml:ï html:Âx“¿and“ïhtml:ï html:Ây¿.‘ úThe“way“to“add“them“to“the“ïhtml:ï html:ÂprobeMap“¿is“to“add“the“followingŽ¡‘Htwo–?ýlines“of“code“to“the“above.ŽŸïhtml:ï html:¦‘$Â[probeMap–ffaddProbe:“[probeLibrary“getProbeForVariable:“"x"Ž¦‘)ffinClass:–ff[Agent2d“class]]];Ž¦‘Dfd[probeMap–ffaddProbe:“[probeLibrary“getProbeForVariable:“"y"Ž¦‘)ffinClass:–ff[Agent2d“class]]];ŽŸbÌïhtml:ï html:Ÿ ñ÷‘<¿And–?ýthat's“it!‘ úThe“two“superclass-declared“variables,“which“are,“in“fact,“instanceŽ¡‘Hvariables–?ýof“the“instance“of“the“subclass,“are“now“included“in“the“probe.ŽŸ8äïhtml:ï html:© ß‘<In–?ýaddition,“a“convenience“message“has“been“added“to“the“ïhtml:ï html:CustomProbeMap“interfaceŽ¡‘Hto–?ýcompress“the“above“rather“cluttered“mechanism“into“one“message.‘ úThis“convenienceŽ¡‘Hmessage–?ýcan“be“used“in“the“usual“case“where“a“ïhtml:ï html:ProbeMap“will“consist“of“variablesŽ¡‘Hand–?ýmessages“from“the“same“class.‘ úFor“example,“the“first“part“of“the“customŽ¡‘Hprobe–?ýcreation“above“can“be“shortened“to:ŽŸ8äïhtml:ï html:¦‘$Â[probeLibrary–ffcreate:“[self“getZone]“forClass:“[person“class]ŽŸTÃ‘DfdwithIdentifiers:–ff"room",“"party",“"name",“"stillhere",ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ú†§ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ’ŸîÂ"listOfFriends",–ff"myColor",“NULL];Ž¤C^‘/ºâ¿And–?ýif“the“user“wanted“messages“in“the“probe“as“well,“it“could“be“extended“to:ŽºâŸ8äïhtml:ï html:© z‘$ÂprobeMap–ff=“[CustomProbeMap“create:“[self“getZone]Ž¡’°f\forClass:–ff[person“class]Ž¡’Š™’withIdentifiers:–ff"room",“"party",“"name",Ž¡’ 3*"stillhere",–ff"listOfFriends",“"myColor",Ž¡’ 3*":",Ž¡’ 3*"setWorld:Room:Party:",Ž¡’ 3*"setPerson:Topic_array:ShowSpeech:",Ž¡’ 3*NULL];ŽŸýoïhtml:ï html:ŸEï‘<¿At–?ýpresent,“this“message“doesn't“search“the“superclasses“for“the“message“namesŽ¤‘Hlisted–?ýhere.‘ úBut,“that“will“soon“be“rectified.ŽŸcïhtml:ï html:Ÿïhtml:ï html:Ÿ ßÑ‘0ïcolor push Black2.ï color popŽŽ‘<ïhtml:ï html:ActivityControl–?ýIssues:‘ úIt“is“completely“reasonable“to“assume“that“explicit“controlŽ¡‘<can–?ýbe“had“over“all“the“activities“in“a“simulation.‘ úHowever,“at“present,“thisŽ¡‘<control–?ýis“limited“because“the“context“in“which“an“activity“runs“determines“howŽ¡‘<it–?ýbehaves.‘ úTo“understand“how“an“ïhtml:ï html:ActivityControl“is“to“be“used,“we“will“have“toŽ¡‘<explore–?ýthe“behavior“of“activities“in“context.‘ ú(For“a“more“complete“explanationŽ¡‘<of–?ýthe“behavior“of“activities,“see“the“ïhtml:ï html:ïhtml:ï html:activity“libraryïhtml:ï html:Ž¤C^‘0(../activity.html)Ž¡‘0documentation.)ŽŸÕSïhtml:ï html:Ÿn‘<There–?ýare“two“ways“to“get“an“activity“started,“one“can“activate“the“activity“inŽ¤‘Hïhtml:ï html:Ânil–?ý¿or“in“some“other“activity.‘ úSo“called“"top-level"“activities“are“activatedŽ¡‘Hin–?ýïhtml:ï html:Ânil“¿and“are“intended“to“be“independent“of“the“sophisticated“scheduling“activityŽ¡‘Hthat–?ýdictates“the“execution“of“actions“in“any“other“context“in“the“simulation.Ž¡‘HI.e.‘ úthe–?ýonly“activities“that“should“be“activated“in“ïhtml:ï html:Ânil“¿are“those“sets“of“eventsŽ¡‘Hthat–?ýare“expected“to“preserve“the“same“behavior“no“matter“what“goes“on“in“anyŽ¡‘Hother–?ýpart“of“the“simulation.ŽŸ8äïhtml:ï html:¦‘<The–?ýother“type“of“activity,“those“activated“in“some“other“activity,“is“intendedŽ¡‘Hto–?ýbe“an“integral“part“of“its“owner“activity.‘ úHowever,“this“doesn't“mean“thatŽ¡‘Hit–?ýïhtml:ï html:must“depend“on“the“outcome“of“actions“happening“in“the“owner“activity.‘ úInŽ¡‘Hfact,–?ýan“ïhtml:ï html:ActionPlan“can“be“designated“as“containing“actions“that“are“capableŽ¡‘Hof–?ýbeing“processed“in“parallel,“via“code“like“the“following:ŽŸ8äïhtml:ï html:¦‘$Â[anActionPlan–ffsetDefaultOrder:“Concurrent];ŽŸC^‘0¿But–?ýthese“activities“are“ïhtml:ï html:still“intended“to“be“meshed“with“their“owner“activities.Ž¡‘<In–?ýother“words,“they“are“part“and“parcel“of“the“same“model“or“simulation.ŽŸ8äïhtml:ï html:¦‘<Now,–?ýthe“operational“effect“of“activating“an“activity“in“ïhtml:ï html:Ânil“¿is“that“it“will“notŽ¡‘Hbe–?ýmeshed“with“the“rest“of“the“Swarm“activity“structure.‘ úThis“gives“the“userŽ¡‘H(or–?ýprocess)“complete“control“over“the“execution“of“that“activity.‘ úA“ïhtml:ï html:Ârun“¿onŽ¡‘Hthat–?ýactivity“will“run“either“to“completion“or“until“a“stop“flag“is“set“by“aŽ¡‘Hsequence–?ýof“events“purely“internal“to“that“activity.‘ úOr,“one“can“stop“it“fromŽ¡‘Hthe–?ýoutside“with“a“message“from“something“like“an“ïhtml:ï html:ActivityControl.ŽŸ8äïhtml:ï html:¦‘<What–?ýall“this“means“is“that,“while“one“can“attach“an“ïhtml:ï html:ActivityControl“to“ïhtml:ï html:any“activity,Ž¡‘Honly–?ýthe“"top-level"“activities“(those“having“been“activated“in“ïhtml:ï html:Ânil¿)“are“goingŽ¡‘Hto–?ýrespond“well“to“it.‘ úAny“sub-activity“will“respond“half-heartedly,“if“at“all.Ž¡‘HFor–?ýexample,“in“the“ïhtml:ï html:Mousetrap“demo“distributed“with“Swarm,“an“ïhtml:ï html:ActivityControlŽ¡‘Hhas–?ýbeen“placed“on“both“the“ïhtml:ï html:ObserverSwarm“and“the“ïhtml:ï html:ModelSwarm“activities.‘ úNow,ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Û–G “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Gºâ¿if–?ýone“sends“a“ïhtml:ï html:Ârun“¿message“to“the“ïhtml:ï html:ActivityControl“that“is“attached“to“the“ïhtml:ï html:Âob-Ž¤‘GºâserverSwarm¿'s–?ýactivity,“the“entire“model“continues“to“run“to“completion,“unlessŽ¡‘Gºâthe–?ýuser“sends“a“ïhtml:ï html:Âstop“¿message.‘ úHowever,“if“the“sim“is“stopped“at“some“point,Ž¡‘Gºâa–?ýïhtml:ï html:Ârun“¿message“to“the“ïhtml:ï html:ÂmodelSwarm¿'s“activity“will“have“no“effect“at“all.‘ ú(ïhtml:ï html:Note:Ž¡‘GºâIf–?ýyou“do“this“via“the“activity“controllers,“you“see“the“ïhtml:ï html:ÂcurrentTime“¿variableŽ¡‘Gºâget–?ýupdated;“but,“the“actual“ïhtml:ï html:Ârun“¿message“to“the“activity,“itself,“has“no“effect.)ŽºâŸ8äïhtml:ï html:Ÿ Ç‘<So,–?ýthe“rule“of“thumb,“for“the“present,“is“to“attach“ïhtml:ï html:ActivityControl“objects“onlyŽ¡‘Hto–?ý"top-level"“activities,“like“the“ïhtml:ï html:ObserverSwarm.Ž©‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(UsageGuide.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(../objectbase.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(InterfaceDesign.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ü¨E “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Swarmobject–/Library:‘m™Interface“Design“NotesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¿Unfortunately,–?ýthis“interface“has“not“undergone“a“rigorous“design“review.‘ úAs“suchŽ¡‘0it–?ýis“subject“to“change“in“the“future.‘ úHowever,“there“are“rumours“that“this“libraryŽ¡‘0will–?ýbe“integrated“into“the“ïhtml:ï html:ïhtml:ï html:defobj“libraryïhtml:ï html:Ž¡‘0(../defobj.html)Ž¡‘0anyway.‘ úSo,–?ýeven“though“little“thought“was“given“to“the“design“of“this“interfaceŽ¡‘0(and–?ýit“is“not“likely“to“be“worthwhile“designing“a“robust“interface“at“this“time),Ž¡‘0it–?ýwas“implemented“in“order“to“provide“a“first“step“towards“bringing“all“the“variousŽ¡‘0libraries–?ýin“line“with“the“standard“set“by“ïhtml:ï html:defobj.Ž©8äïhtml:ï html:¤ Ç‘0Along–?ýthese“lines,“a“few“notes“are“relevant.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¡‘0ïcolor push Black1.ï color popŽŽ‘<ïhtml:ï html:Probes–?ýmay“become“an“inherent“part“of“any“object.Ž¦ïhtml:ï html:¡‘0ïcolor push Black2.ï color popŽŽ‘<ïhtml:ï html:ActivityControls–?ýwill“become“a“part“of“a“larger“set“of“tools“used“for“debuggingŽ¤‘<Swarm‘?ýmodels.ŽŸïhtml:ï html:¡‘0ïcolor push Black3.ï color popŽŽ‘<The–?ýexplicit“importation“of“the“ïhtml:ï html:SwarmObject“interface“should“be“removed.‘ úThisŽ¡‘<is–?ýonly“provided“for“backward“compatibility“and“when“all“the“libraries“follow“theŽ¡‘<interface–?ýconventions,“then“those“conventions“should“be“encouraged.Ž©‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(AdvancedUsage.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(../objectbase.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(Implementation.html)Ž¦‘0„¤ŽŽ¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Ý°c “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Swarmobject–/Library:‘m™Implemenation“NotesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:©ïhtml:ï html:¤‘0ïcolor push Black¿1.ï color popŽŽ‘<Right–?ýnow,“ïhtml:ï html:Probe's“rely“on“a“special“method,“ïhtml:ï html:ÂgetInstanceName¿,“that“has“to“be“implementedŽ¡‘<in–?ýany“probe-able“object“in“order“to“get“anything“other“than“the“class“name“ofŽ¡‘<that–?ýobject“into“the“object“designation“widget.‘ úHowever,“a“more“general“capabilityŽ¡‘<has–?ýbeen“added“to“ïhtml:ï html:defobj“to“give“a“meaningful“name“to“any“object.‘ úïhtml:ï html:Probes“willŽ¡‘<be–?ýchanged“to“take“advantage“of“this“new“capability.ŽŸ8äïhtml:ï html:¦ïhtml:ï html:Ÿ Ç‘0ïcolor push Black2.ï color popŽŽ‘<In–?ýthe“ïhtml:ï html:ActivityControl“the“frequency“of“the“message“ïhtml:ï html:ÂupdateStateVar“¿is“very“high.Ž¡‘<It–?ýis“sent“at“least“once“every“cycle“and“ïhtml:ï html:every“time“a“message“is“sent“to“the“ïhtml:ï html:ActivityControl.Ž¡‘<This–?ýis“unsatisfactory.‘ úSome“of“these“messages“can“be“pruned“out“of“the“object.ŽŸ8äïhtml:ï html:¦ïhtml:ï html:Ÿ Ç‘0ïcolor push Black3.ï color popŽŽ‘<The–?ýïhtml:ï html:ÂprobeMap“¿designed“for“use“with“an“ïhtml:ï html:ActivityControl“was“chosen“fairly“arbitrarily.Ž¡‘<Right–?ýnow,“it“serves“as“a“default“for“the“class.‘ úA“user“can“override“it“by“designingŽ¡‘<a–?ýnew“one“and“inserting“it“into“the“ïhtml:ï html:ÂprobeLibrary¿.ŽŸ8äïhtml:ï html:¦ïhtml:ï html:Ÿ Ç‘0ïcolor push Black4.ï color popŽŽ‘<Errors–?ýspecific“to“objects“in“the“ïhtml:ï html:objectbase“library“need“to“be“gathered“and“initializedŽ¡‘<like–?ýthose“in“the“ïhtml:ï html:defobj“library.Ž©‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(InterfaceDesign.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(../objectbase.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(../objectbase.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹Þ», “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Swarm–/Space“LibraryŽŸ•Ç¿The–?ýSwarm“Space“library“is“the“beginnings“of“a“library“to“assist“in“building“environments“forŽ¤interacting–?ýagents.‘ úIn“general,“environments“can“be“just“as“varied“as“the“agents“themselvesŽ¡(in–?ýone“view,“the“environment“itself“is“simply“another“agent).‘ úHowever,“many“simulations“haveŽ¡similar–?ýtypes“of“environments“that“can“be“helpfully“supported“by“generic“code.ŽŸªïhtml:ï html:Ÿ ë¼‘0The–?ýcurrent“space“library“only“addresses“simple“kinds“of“discretized“2d“space.‘ úImprovementŽ¡‘0is–?ýplanned“in“the“future:‘ úsee“the“ïhtml:ï html:todo“listïhtml:ï html:Ž¤$ ‘0(../todo.html)Ž¡‘0for–?ýideas.‘ úBriefly,“coordinates“need“to“be“elevated“to“the“status“of“objects,“whichŽ¤‘0should–?ýhopefully“allow“spaces“of“different“scales“and“boundary“conditions“to“interactŽ¡‘0through–?ýa“common“reference“system.‘ úIn“addition,“other“types“of“spaces“are“desired:Ž¡‘0continuous–?ýcoordinates,“other“dimensions,“arbitrary“graphs,“etc.ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽ¤G®ïhtml:ï html:Ÿá ÀDiscr°gete2dŽŸÊƒ¿Root–?ýclass“of“all“2d“discrete“spaces.› úA“Discrete2d“is“basically“a“2d“array“of“ids.˜SubclassesŽ¡add–?ýparticular“space“semantics“onto“this.‘ úCurrently“Discrete2d“grids“are“accessed“by“integerŽ¡pairs–?ýof“X“and“Y“coordinates.Ž©ŸJïhtml:ï html:Ÿ3jÅCr½«eationŽŸ 9 ïhtml:ï html:¤ïhtml:ï html:ïhtml:ï html:Ÿë€‘:Â-–ffsetSizeX:“(int)x“Y:“(int)yŽŸbÌïhtml:ï html:Ÿ ÁÔ‘X¿Set–?ýthe“world“size.Ž¡ïhtml:ï html:ïhtml:ï html:Ÿ$ ‘:Â-‘ffcreateEndŽžÉïhtml:ï html:Ÿ×‘X¿Create–?ýthe“lattice,“precompute“the“offsets“based“on“Y“coordinate.Ž¦ïhtml:ï html:Ÿ3jÅQuerying–™™Discr½«ete2d“stateŽ©î&ïhtml:ï html:¡ïhtml:ï html:ïhtml:ï html:Ÿ 6z‘:Â-–ff(int)getSizeX“and“-“(int)getSizeYŽŸbÌïhtml:ï html:Ÿ ÁÔ‘X¿Get–?ýthe“size“of“the“lattice.ŽŸffïhtml:ï html:ŸlNÅGlobal‘™™OperationsŽ¦ïhtml:ï html:¡ïhtml:ï html:ïhtml:ï html:Ÿ 6z‘:Â-‘fffastFillWithValue:‘ ÌÌ(int)aValueŽ¤ýoïhtml:ï html:ïhtml:ï html:Ÿ'1‘:-‘fffastFillWithObject:‘ ÌÌanObjectŽŸbÌïhtml:ï html:ïhtml:ï html:Ÿ ÁÔ‘:-‘fffillWithValue:‘ ÌÌ(int)aValueŽ¡ïhtml:ï html:ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ßÇ% “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘9ºâÂ-‘fffillWithObject:‘ ÌÌanObjectŽºâ©bÌïhtml:ï html:Ÿw>‘X¿These–?ýmethods“will“fill“the“entire“space“with“a“specified“value“or“object.Ž¤‘XThe–?ýdifference“between“the“`fill'“and“`fastFill'“methods“is“that“the“formerŽ¡‘Xuse–?ýïhtml:ï html:ÂputObject“¿and“ïhtml:ï html:ÂputValue“¿internally,“in“other“words,“they“are“sensitiveŽ¡‘Xto–?ýany“subclassing“and“alteration“of“these“methods,“whereas“the“latter“useŽ¡‘Xïhtml:ï html:low–?ýlevel“access“routinesïhtml:ï html:ŽŸÚ ‘Xdirectly–?ýand“are“therefore“much“faster“(and“remain“unaffected“by“subclassing).ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ ¡&‘:Â-–ffcopyDiscrete2d:› ÌÌ(Discrete2d“*)a“toDiscrete2d:˜(Discrete2d“*)b;Ž¦ïhtml:ï html:Ÿw>‘X¿This–?ýmethod“copies“the“data“in“one“Discrete2d“object“to“another“Discrete2dŽ¡‘Xobject.‘ úIt–?ýassumes“that“both“objects“already“exist.ŽŸ8äïhtml:ï html:ïhtml:ï html:© ¡&‘:Â-–ff(int)setDiscrete2d:› ÌÌ(Discrete2d“*)a“toFile:˜(const“char“*)filename;ŽŸýoïhtml:ï html:ŸÜ›‘X¿This–?ýmethod“reads“a“PGM“formatted“file“and“pipes“the“data“into“a“Discrete2dŽ¡‘Xobject.ŽŸŸJïhtml:ï html:ŸèÔÅAccessing‘™™elementsŽŸ}á¿The–?ýDiscrete2d“is“essentially“a“2d“array“of“ids.‘ úHowever,“we“also“allow“users“to“access“theŽ¡array–?ýas“if“it“were“an“array“of“integers:› úthe“integers“are“cast“into“ids“for“storage.˜TheŽ¡Object–?ýmethods“retrieve“values“as“objects,“the“Value“methods“cast“things“to“integers“beforeŽ¡returning.‘ úWe–?ýbelieve“this“is“safe“on“all“architectures.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:¦‘:Â-–ffgetObjectAtX:“(int)x“Y:“(int)yŽ¤bÌïhtml:ï html:Ÿw>‘X¿Return–?ýthe“pointer“stored“at“(x,y).ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:Â-–ffgetValueAtX:“(int)x“Y:“(int)yŽ¡ïhtml:ï html:Ÿw>‘X¿Return–?ýthe“integer“stored“at“(x,y).ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:Â-–ffputObject:‘ ÌÌanObject“atX:“(int)x“Y:“(int)yŽ¡ïhtml:ï html:Ÿw>‘X¿Put–?ýthe“given“pointer“to“(x,y)“overwriting“whatever“was“there.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:Â-–ffputValue:‘ ÌÌ(int)v“atX:“(int)x“Y:“(int)yŽ¡ïhtml:ï html:Ÿw>‘X¿Put–?ýthe“given“integer“to“(x,y)“overwriting“whatever“was“there.ŽŸŸJïhtml:ï html:ŸèÔÅLo•Û$w›™™leÈ½v“el˜accessŽŸ}á¿For–?ýspeed,“sometimes“you“want“to“go“below“the“method“call“layer“and“access“cells“quickly.‘ úToŽ¤allow–?ýthis“Discrete2d“defines“some“macros“that“give“you“internal“access.‘ úUse“these“at“yourŽ¡own–?ýperil!‘ úIn“particular,“subclasses“have“no“way“to“redefine“the“macros.ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:¦‘:Â-–ff(id“*)getLatticeŽ¤bÌïhtml:ï html:Ÿw>‘X¿Returns–?ýthe“lattice“pointer“-“use“this“for“fast“access.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:Â-–ffdiscrete2dSiteAt(lattice,“offsets,“x,“y)Ž¡ïhtml:ï html:Ÿw>‘X¿Macro–?ýto“return“a“pointer“to“the“value“at“site“x,“y.‘ úlattice“is“the“returnŽŸ‘Xvalue–?ýfrom“getLattice,“offsets“is“the“precomputed“offsets“(stored“in“self->offsets).ŽŸŸJïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹àÒz “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâÅMiscellaneousŽŸ¿nºâ¿These–?ýmethods“are“used“in“ïhtml:ï html:Â-‘ffcreateEnd“¿to“actually“allocate“the“array.‘ úSubclasses“might“needŽ¤ºâto–?ýuse“these.ŽºâŸ ïhtml:ï html:©ïhtml:ï html:ïhtml:ï html:Ÿ—‘:Â-‘ffmakeOffsetsŽž+Ãïhtml:ï html:ŸïÔ‘X¿Given–?ýan“array“size,“compute“the“offsets“array“that“caches“the“multiplicationŽ¡‘Xby–?ýysize.‘ úSee“the“ïhtml:ï html:Âdiscrete2dSiteAt“¿macro.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ â³‘:Â-–ff(id“*)allocLatticeŽŸýoïhtml:ï html:Ÿ(‘X¿Allocate–?ýmemory“for“the“lattice.ŽŸ‘0„¤ŽŽ¤G®ïhtml:ï html:ŸØÀGrid2dŽŸÁz¿Grid2d–?ýis“a“generic“container“class“to“represent“agent“position“on“a“2d“lattice.‘ úIt“gets“mostŽ¡of–?ýits“behaviour“from“Discrete2d,“adding“extra“code“to“check“that“you“don't“overwrite“thingsŽ¡by–?ýaccident.› úGrid2d“is“pretty“primitive:˜only“one“object“can“be“stored“at“a“site,“no“boundaryŽ¡conditions–?ýare“implied,“etc.‘ úA“fancier“Grid2d“is“in“the“works.Ž¤ŸJïhtml:ï html:Ÿ*aÅNew‘™™MethodsŽŸ 9 ïhtml:ï html:¦ïhtml:ï html:ïhtml:ï html:Ÿâw‘:Â-‘ffsetOverwriteWarnings:‘ ÌÌ(BOOL)bŽŸbÌïhtml:ï html:Ÿ ¸Ë‘X¿If–?ýset“to“true,“then“if“you“try“to“store“something“at“a“site“that“doesn'tŽŸ‘Xhave–?ý0x0“there,“a“warning“will“be“generated.Ž¡ïhtml:ï html:Ÿ*aÅOvÛ$erridden‘™™methodsŽŸ 9 ïhtml:ï html:¦ïhtml:ï html:ïhtml:ï html:Ÿâw‘:Â-–ffputObject:‘ ÌÌanObject“atX:“(int)x“Y:“(int)yŽ©bÌïhtml:ï html:Ÿ ¸Ë‘X¿Replaces–?ýthe“Discrete2d“method.‘ úFirst“check“to“see“if“it“should“do“overwriteŽ¤‘Xwarnings,–?ýand“if“so“if“you're“going“to“overwrite:‘ úif“both“conditions“areŽ¡‘Xtrue,–?ýprint“out“a“warning“message.‘ úRegardless“of“the“check,“it“writes“theŽ¡‘Xnew–?ýobject“in.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ â³‘:Â+‘ffcreateBegin:‘ ÌÌaZoneŽ¦ïhtml:ï html:Ÿ ¸Ë‘X¿Make–?ýoverwrite“warnings“be“on“by“default.ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸØÀDblBuer2dŽŸÁz¿DblBuffer2d–?ýaugments“Discrete2d“to“provide“a“form“of“double“buffered“space.‘ úTwo“lattices“areŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹áá/ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿maintained:› úlattice–?ý(the“current“state),“and“newLattice“(the“future“state).˜All“reads“takeŽ¤G®ºâplace–?ýfrom“lattice,“all“writes“take“place“to“newLattice.‘ únewLattice“is“copied“to“lattice“whenŽ¡ºâïhtml:ï html:Â-‘ffupdateLattice–?ý¿is“called.‘ úDblBuffer2d“can“be“used“to“implement“one“model“of“concurrent“action,Ž¡ºâlike–?ýin“Ca2ds.‘ úïhtml:ï html:NOTE:“be“very“careful“if“you're“using“low-level“macro“access“to“the“world,Ž¡ºâin–?ýparticular“be“sure“that“you“preserve“the“write“semantics“on“the“newLattice.ŽºâŸŸJïhtml:ï html:ŸD:ÅNew‘™™MethodsŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:ŸüP‘:Â-‘ffupdateLatticeŽ¤bÌïhtml:ï html:© Ò¤‘X¿Copy–?ýnewLattice“to“lattice,“in“effect“updating“the“lattice.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ üŒ‘:Â-–ff(id“*)getNewLatticeŽ¡ïhtml:ï html:¦‘X¿Like›?ýïhtml:ï html:Â-–ff(id“*)getLattice¿:‘ úreturn˜a˜pointer˜to˜the˜newLattice˜buffer.ŽŸŸJïhtml:ï html:ŸD:ÅOvÛ$erridden‘™™MethodsŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:ŸüP‘:Â-‘ffcreateEndŽžÉïhtml:ï html:Ÿ§‘X¿Rewrites–?ýthe“method“from“Discrete2d.‘ úAllocate“two“lattices,“makes“the“offsets.ŽŸcïhtml:ï html:ïhtml:ï html:Ÿ Ñã‘:Â-–ffputObject:› ÌÌanObject“atX:“(int)x“Y:“(int)y–?ý¿and“ïhtml:ï html:Â-–ffputValue:˜(int)value“atX:ŽŸ‘D(int)x–ffY:“(int)y‘?ý¿andŽ¡ïhtml:ï html:¦‘XOverridden–?ýso“writes“happen“to“newLattice.ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸñÚÀCa2dŽŸÛS¿Inherits–?ýfrom“DblBuffer2d,“defines“abstract“protocol“for“cellular“automata.ŽŸŸJïhtml:ï html:ŸD:ÅNew‘™™MethodsŽŸ 9 ïhtml:ï html:¤ïhtml:ï html:ïhtml:ï html:ŸüP‘:Â-‘ffsetNumStates:‘ ÌÌ(int)dŽŸýoïhtml:ï html:Ÿ8‘X¿Record–?ýthe“number“of“states“the“CA“understands.Ž¡ïhtml:ï html:ïhtml:ï html:Ÿ5p‘:Â-‘ffinitializeLatticeŽžÉïhtml:ï html:Ÿ§‘X¿Use–?ýthis“to“set“up“your“CA“to“a“default“initial“state.‘ úUnimplemented“in“Ca2d.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ üŒ‘:Â-‘ffstepRuleŽŸbÌïhtml:ï html:¦‘X¿One–?ýiteration“of“the“CA“rule.‘ úUnimplemented“in“Ca2d.ŽŸŸJïhtml:ï html:ŸD:ÅOvÛ$erridden‘™™MethodsŽŸ 9 ïhtml:ï html:¡ïhtml:ï html:ïhtml:ï html:ŸüP‘:Â-‘ffcreateEndŽžÉïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹âë “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Wºâ¿Check–?ýthat“numStates“has“been“set.ŽŸ‘/ºâ„¤ŽŽºâŸG®ïhtml:ï html:ŸçÀConwayLife2dŽŸ`¿Classic–?ý2d“Conway's“Life“CA.ŽŸŸJïhtml:ï html:ŸiGÅOvÛ$erridden‘™™MethodsŽŸ 9 ïhtml:ï html:¤ïhtml:ï html:ïhtml:ï html:Ÿ!]‘:Â+createBegin:‘ ÌÌaZoneŽ©bÌïhtml:ï html:Ÿ ÷±‘X¿Set–?ýnumber“of“states“to“2.Ž¡ïhtml:ï html:ïhtml:ï html:ŸZ}‘:Â-‘ffinitializeLatticeŽžÉïhtml:ï html:Ÿ=´‘X¿Initialize–?ýlattice“to“random“1/3“in“state“1.ŽŸÕSïhtml:ï html:ïhtml:ï html:Ÿ…*‘:Â-‘ffstepRuleŽ¦ïhtml:ï html:Ÿ ÷±‘X¿Run–?ýConway's“Life“rule“(simpleminded“version).ŽŸ‘0„¤ŽŽ¤G®ïhtml:ï html:ŸçÀDiuse2dŽŸ`¿Discrete–?ý2nd“order“approximation“to“2d“diffusion“with“evaporation.‘ úMath“is“done“in“integersŽ¡on–?ýthe“range“[0,0x7fff].Ž¤ŸJïhtml:ï html:ŸiGÅNew‘™™MethodsŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿ!]‘:Â-‘ffsetDiffusionConstant:‘ ÌÌ(double)dŽŸýoïhtml:ï html:Ÿ]‘X¿Set–?ýthe“diffusion“constant.‘ úValues“over“1.0“might“not“be“valid.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ !™‘:Â-‘ffsetEvaporationRate:‘ ÌÌ(double)dŽ¦ïhtml:ï html:Ÿ ÷±‘X¿Set–?ýthe“evaporation“rate.‘ úValues“over“1.0“don't“make“much“sense.Ž¡ïhtml:ï html:ŸiGÅOvÛ$erridden‘™™MethodsŽŸ 9 ïhtml:ï html:¤ïhtml:ï html:ïhtml:ï html:Ÿ!]‘:Â+createBegin:‘ ÌÌaZoneŽ¦ïhtml:ï html:Ÿ ÷±‘X¿Set–?ýdiffusion“constant“and“evaporation“rate“to“1.0,“numStates“to“0x7fff.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ !™‘:Â-‘ffinitializeLatticeŽžÉïhtml:ï html:Ÿ=´‘X¿Initialize–?ýworld“to“0.Ž¡ïhtml:ï html:ïhtml:ï html:ŸZ}‘:Â-‘ffstepRuleŽ¦ïhtml:ï html:Ÿ ÷±‘X¿Run–?ýdiscrete“approximation“to“diffusion.‘ úRoughly,“it'sŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ã÷ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘Wºâ¿newHeat–?ý=“evapRate“*“(self“+“diffuseConstant*(nbdavg“-“self))ŽºâŸ8äïhtml:ï html:©,‘Xwhere–?ýnbdavg“is“the“weighted“average“of“the“8“neighbours.ŽŸ‘0„¤ŽŽ¤G®ïhtml:ï html:ŸzÀObject2dDisplayŽŸêó¿Object2dDisplay–?ýhelps“display“2d“arrays“of“objects.‘ úCreate“a“Object2dDisplay,“give“it“a“RasterŽ¡widget–?ýto“draw“on,“a“Discrete2d,“a“message“to“call“on“each“object,“and“(optionally)“a“collectionŽ¡of–?ýobjects“and“it“will“dispatch“the“message“to“all“objects“with“the“Raster“widget“as“an“argument.Ž¡In–?ýaddition,“Object2dDisplay“can“help“you“make“probees.ŽŸŸJïhtml:ï html:ŸSÚÅCr½«eation‘™™PhaseŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿ ð‘:Â-–ffsetDisplayWidget:‘ ÌÌ(Raster“*)rŽ¤bÌïhtml:ï html:ŸâD‘X¿Set–?ýthe“display“widget“to“use“for“drawing.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:Â-–ffsetDiscrete2dToDisplay:‘ ÌÌ(Discrete2d“*)cŽ¡ïhtml:ï html:ŸâD‘X¿Set–?ýthe“2d“array“to“drawŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:Â-‘ffsetDisplayMessage:‘ ÌÌ(SEL)sŽ¡ïhtml:ï html:ŸâD‘X¿Set–?ýthe“message“to“be“sent“to“each“object“in“the“grid“to“make“it“draw“itself.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:Â-‘ffsetObjectCollection:‘ ÌÌobjectsŽ¡ïhtml:ï html:©âD‘X¿(optional)–?ýset“a“collection“of“objects“to“be“displayed.‘ úIf“this“is“not“given,Ž¤‘Xthen–?ýObject2dDisplay“loops“through“the“2d“grid“sending“draw“messages“to“allŽ¡‘Xobjects–?ýit“finds“there.‘ úGiving“an“explicit“collection“of“objects“to“drawŽ¡‘Xis–?ýmore“efficient“if“your“grid“is“sparsely“populated.ŽŸŸJïhtml:ï html:ŸSÚÅUseŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿ ð‘:Â-‘ffdisplayŽŸbÌïhtml:ï html:¦‘X¿Draw–?ýall“objects“in“the“array“(or“optionally,“the“collection)“on“the“rasterŽ¡‘Xwidget.‘ úAll–?ýthat“happens“here“is“the“display“message“is“sent“to“each“objectŽ¡‘X-–?ýit“is“the“object's“responsibility“to“render“itself.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ,‘:Â-–ffmakeProbeAtX:“(int)x“Y:“(int)yŽŸbÌïhtml:ï html:¦‘X¿Find–?ýan“object“at“the“given“(x,y)“coordinate“and“build“a“probe“display“forŽ¡‘Xit.‘ úThis–?ýis“a“good“method“to“make“a“button“client“for“a“raster“widget“likeŽŸ8äïhtml:ï html:Ÿ,‘0Â[aRaster–ffsetButtonClient:“aObject2dDisplay“Message:“M(makeProbeAtX:Y:)]ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ä X “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÑçåºâÀV‘þialue2dDisplayŽŸg¾ºâ¿Value2dDisplay–?ýhelps“display“2d“arrays“of“values.‘ úValue2dDisplay“goes“through“a“given“Discrete2dŽŸG®ºâarray,–?ýturn“states“into“colours,“and“draws“them“into“a“Raster“widget.ŽºâŸŸJïhtml:ï html:ŸÐ¥ÅCr½«eation‘™™PhaseŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿˆ»‘:Â-–ffsetDisplayWidget:› ÌÌ(Raster“*)r“Colormap:˜(XColormap“*)cŽ¤bÌïhtml:ï html:©_‘X¿Set–?ýthe“display“widget“and“the“colourmap“to“use“to“draw“the“value“array.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ ˆ÷‘:Â-–ffsetDiscrete2dToDisplay:‘ ÌÌ(Discrete2d“*)cŽ¡ïhtml:ï html:¦‘X¿Set–?ýwhich“array“to“draw.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ ˆ÷‘:Â-–ffsetDisplayMappingM:“(int)m“C:“(int)cŽ¡ïhtml:ï html:¦‘X¿Linear–?ýtransform“of“states“to“colours“for“drawing.ŽŸ8äïhtml:ï html:Ÿ ˆ÷‘Xcolor–?ý=“state“/“m“+“cŽŸÕSïhtml:ï html:Ÿìˆ‘XIf–?ýnot“set,“assume“m“==“1“and“c“==“0.ŽŸÉóïhtml:ï html:Ÿ¥üÅUseŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿˆ»‘:Â-‘ffdisplayŽ¡ïhtml:ï html:¦‘X¿Draw–?ýthe“array“on“the“given“widget.‘ úNote“that“you“still“have“to“tell“theŽ¤‘Xwidget–?ýto“draw“itself“afterwards.‘ úThe“code“for“display“uses“the“fast“macroŽ¡‘Xaccess–?ýin“Discrete2d“on“the“cached“return“value“from“getLattice.‘ úIt“alsoŽ¡‘Xcaches–?ýthe“ïhtml:ï html:ÂdrawPointX:Y:“¿method“lookup“on“the“display“widget“-“this“is“a“niceŽ¡‘Xtrick–?ýthat“you“might“want“to“look“at.ŽŸ‘0„¤ŽŽ¤G®ïhtml:ï html:Ÿ~EÀInt2dFilerŽŸg¾¿The–?ýInt2dFiler“class“is“used“to“save“the“state“of“any“Discrete2d“object“(or“a“subclass“thereof)Ž¡to–?ýa“specified“file.ŽŸŸJïhtml:ï html:ŸÐ¥ÅA–™™Note“on“Output“F£×ormatsŽŸe²¿The–?ýissue“of“what“format(s)“the“class“should“know“about“is“still“open.‘ úFor“the“purposes“thatŽŸI–?ýhave“encountered,“simply“storing“the“values“in“space-delimited“line“format:ŽŸ Ü»ïhtml:ï html:ïhtml:ï html:Ÿ ˆ÷‘0Âvalue0_0–ffvalue0_1“...Ž¤ÁÛ‘0value1_0–ffvalue1_1“...Ž¡‘0...Ž¡‘0...ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹å “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿has–?ýbeen“sufficient.‘ úIn“particular,“the“output“of“this“class“has“been“used,“in“conjunctionŽ¤ºâwith–?ýthe“ïhtml:ï html:fragstatsïhtml:ï html:Ž¡ºâ(ftp://ftp.fsl.orst.edu/pub/fragstats.2.0/)Ž¡ºâpackage,–?ýto“apply“landscape“metrics“to“the“output“of“a“Swarm“simulation.‘ úNevertheless,“I“(ïhtml:ï html:ManorŽ¡ºâAskenaziïhtml:ï html:Ž¡ºâ(mailto:‘ úmanor@santafe.edu)Ž¡ºâ)–?ýwould“be“very“interested“in“hearing“from“end-users“about“any“other“(presumably“more“complexŽ¡ºâformats),–?ýas“the“need“arises.ŽºâŸcïhtml:ï html:Ÿïhtml:ï html:ïhtml:ï html:Ÿ œs‘:-–?ýsetDiscrete2dToFile:‘ ú(Discrete2d“*)aSpaceŽŸ8äïhtml:ï html:© Ç‘XSet–?ýthe“target“space“to“be“filled.‘ úThis“message“can“be“used“more“than“once,Ž¡‘Xbut–?ýoften“it“is“useful“to“keep“one“Int2dFiler“per“space“(e.g.‘ úwhen“the“spaceŽ¡‘Xis–?ýsaved“multiple“times).ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:-‘?ýsetValueMessage:‘ ú(SEL)aSelectorŽŸ8äïhtml:ï html:¦‘XThis–?ýmessage“is“optional.‘ úIt“is“used“when“the“target“Discrete2d“containsŽ¡‘Xobjects.‘ úBy–?ýsending“each“object“the“message“specified“by“the“selector,“theŽ¡‘XInt2dFiler–?ýis“able“to“get“from“the“object“an“integer“representing“its“state,Ž¡‘Xwhich–?ýit“then“writes“to“the“file.ŽŸïhtml:ï html:ïhtml:ï html:¡‘:-‘?ýsetBackground:‘ ú(int)aValueŽŸ8äïhtml:ï html:¦‘XThis–?ýmessage“is“optional.‘ úIt“is“used“when“the“target“Discrete2d“containsŽ¡‘Xobjects.‘ úIf–?ýa“particular“location“in“the“space“has“no“resident“object,“theŽ¡‘Xargument–?ýof“this“message“is“the“value“which“gets“writtent“to“the“file.‘ úTheŽ¡‘Xdefault–?ýbackground“value“is“0.ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘:-–?ýfileTo:‘ ú(const“char“*)fileNameŽŸÕSïhtml:ï html:Ÿ*‘XWhen–?ýthe“Int2dFiler“receives“this“message,“it“opens“a“file“called“ïhtml:ï html:¾fileName‘¼r¿,Ž¡‘Xstores–?ýthe“state“of“a“pre-specified“space“into“it,“and“then“closes“the“file.ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:¦‘0¿Last‘?ýmodified:‘ ú1997-12-17ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹æ 8 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Random‘/LibraryŽ©q'‘0„¤ŽŽŸïhtml:ï html:Ÿóe‘0ÊDocumentation–and“Implementation“StatusŽŸ‘0„¤ŽŽŸ)Â’Úqï>PSfile="eps/bomb.eps" llx=290 lly=365 urx=321 ury=396 rwi=310 ŽŽŸ ïhtml:ï html:Ÿo¿Note:› úThe–?ýnew“random“library“does“not“work“in“the“same“way“as“the“old“one.˜This“means“thatŽ¤âsome–?ýapplications“that“used“the“random“library“provided“with“the“1.0.2“release“will“be“ïhtml:ï html:broken.Ž¡However,–?ýporting“these“applications“to“the“new“random“library“will“be“fairly“easy“since“largeŽ¡efforts–?ýwere“made“to“adhere“to“the“standard“set“with“the“last“version“and“some“backwards“compatibilityŽ¡hooks–?ýwere“incorporated.ŽŸõNïhtml:ï html:Ÿ6'½P•Üorting–/to“Random“0.7Ž¦‘0„¤ŽŽŸG®ïhtml:ï html:ŸIiÀOv•ÓÅer“viewŽŸë4¿First,–?ýa“few“thoughts“on“pseudorandom“number“generation.› úIt's“hard“to“do“right.˜There“areŽ¤many–?ýproblems:‘ úthe“root“cause,“of“course,“is“that“computer“algorithms“themselves“are“not“random.Ž¡But–?ýthere“are“also“problems“with“defining“"random",“coming“up“with“good“tests“for“generators,Ž¡and–?ýimplementing“algorithms“correctly“and“efficiently.‘ úThe“history“of“pseudorandom“numberŽ¡generation–?ýin“simulation“work“is“mostly“embarassing.‘ úThis“library“attempts“to“do“a“decentŽ¡job–?ýof“generating“random“numbers,“as“well“as“documenting“how“things“work“and“what“shortcomingsŽ¡there–?ýare.‘ úIf“you“want“to“learn“more“about“random“number“generation,“the“bibliography“[See:Ž¡ïhtml:ï html:Â$(SWARMHOME)/src/random/docs/SOURCES.for.0.7]–?ý¿has“useful“notes.‘ úKnuth“is“the“main“referenceŽ¡in–?ýthis“realm,“but“too“old“to“describe“most“of“the“particular“generators“used“here.ŽŸ—ïhtml:ï html:Ÿ T‘0The–?ýcode“here“represents“an“effort“to“implement“several“efficient,“reasonably“safeŽ¡‘0generators.› úThe–?ýalgorithms“come“from“reading“the“literature“[See:˜ïhtml:ï html:Â$(SWARMHOME)/src/random/docs/SOURCES.for.0.7]¿:Ž¡‘0these–?ýalgorithms“have“been“implemented“as“accurately“as“possible“and“run“through“someŽ¡‘0simple–?ýtests.‘ úThere“is“always“a“chance“that“some“algorithm“here“is“no“good“-“there'sŽ¡‘0also–?ýthe“chance“that“it“is“implemented“incorrectly.ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ç !ÿ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿For–?ýbest“results,“library“users“should“test“these“generators“themselves“in“some“domain-specificŽ¤‘/ºâway.› úOne–?ýeasy“way“to“do“this“is“to“run“an“experiment“twice:˜once“with“one“classŽ¡‘/ºâof–?ýgenerator“(say,“PMMLCG),“and“once“with“another“(say,“SWB).“If“the“results“differŽ¡‘/ºâradically,–?ýthen“you“can“suspect“the“generator.‘ úIf“they“don't,“well,“the“generatorŽ¡‘/ºâstill–?ýmight“be“faulty.ŽºâŸ8äïhtml:ï html:© Ç‘0There–?ýis“also“a“tarball“of“test“programs“for“the“random“number“library“on“the“SwarmŽ¡‘0ftp‘?ýsite:ŽŸ8äïhtml:ï html:ïhtml:ï html:¦‘0SwarmTests-0.7.tar.gzïhtml:ï html:Ž¡‘0(ftp://ftp2.santafe.edu/pub/swarm/RandomTests-0.7.tar.gz)ŽŸ8äïhtml:ï html:ŸÇ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¼jÀDocumentationŽ¤^5¿The–?ýïhtml:ï html:¾random‘üo¿library“is“defined“and“documented“according“to“the“ïhtml:ï html:Library“Interface“Conventionsïhtml:ï html:Ž¡(defobj/library.html)Ž¤.‘ úThe–?ýfollowing“standard“sections“of“documentation“are“available:ŽŸ8äïhtml:ï html:Ÿ ïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface‘?ýReferenceïhtml:ï html:Ž¡‘0(random/Interface.html)ŽŸÕSïhtml:ï html:Ÿ*‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Usage‘?ýGuideïhtml:ï html:Ž¡‘0(random/UsageGuide.html)ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Advanced–?ýUsage“Guideïhtml:ï html:Ž¡‘0(random/AdvancedUsage.html)ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Interface–?ýDesign“Notesïhtml:ï html:Ž¡‘0(random/InterfaceDesign.html)ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Implementation‘?ýNotesïhtml:ï html:Ž¡‘0(random/Implementation.html)ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:¦‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹è ,: “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Random–/Library:‘m™Documentation“andŽŸâImplementation‘/StatusŽŸ©^ïhtml:ï html:ŸÇÉ‘0„¤ŽŽŸ ïhtml:ï html:Ÿ 5‘0¿This–?ýis“version“0.7“of“ïhtml:ï html:¾Random‘¼r¿.› úIt“was“donated“by“Sven“Thommesen.˜Version“0.6“wasŽ¤‘0a–?ýreimplementation“of“most“of“Nelson“Minar's“original“random“with“many“changes“andŽ¡‘0a–?ýnew“interface.‘ úThis“version“adds“manyŽŸ8äïhtml:ï html:¤ ÇQ‘0more–?ýgenerators“and“distributions“and“changes“the“interface“somewhat.ŽŸ8äïhtml:ï html:¡‘0The–?ýimplementation“may“be“a“little“unstable.› úIt“hasn't“been“fully“tested.˜Sven“hasŽ¤‘0also–?ýcontributed“a“test“suite“which“we“will“make“available“on“the“web“site.‘ úBut,Ž¡‘0as–?ýwith“any“pseudo-random“number“generation“library,“results“obtained“from“it“shouldŽ¡‘0be–?ýexamined“very“closely.‘ úBut“we“are“reasonably“sure“the“generators“and“distributionsŽ¡‘0have–?ýbeen“correctly“implemented.ŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿ¼ŸÀDocumentationŽŸ ¢Âïhtml:ï html:Ÿ»¨‘0¿More–?ýdocumentation“is“available“within“the“Swarm“source“distribution,“itself“[Ref:Ž¡‘0ïhtml:ï html:Â$(SWARMHOME)/src/random/docs/¿.‘ úThese–?ýdocs“consist“of:ŽŸ!#ïhtml:ï html:Ÿ ÞÝ‘8ïhtml:ï html:WHATS.NEW.in.0.7ŽŽ¡’• "ïhtml:ï html:Additions–?ýto“Random“since“v.‘ ú0.6ŽŽ¡¡‘8ïhtml:ï html:WHATS.CHANGED.in.0.7ŽŽ¡’• "ïhtml:ï html:Changes–?ýto“Random“since“v.‘ ú0.6ŽŽ¡¡‘8ïhtml:ï html:WHATS.LEFT.TODOŽŽ¡’• "ïhtml:ï html:Improvements–?ýthat“may“make“it“into“v.‘ ú0.8ŽŽ¡¡‘8ïhtml:ï html:README.Generators.v07ŽŽ¡’• "ïhtml:ï html:Usage–?ýGuide“for“generator“objectsŽŽ¡¡‘8ïhtml:ï html:README.Distributions.v07ŽŽ¡’• "ïhtml:ï html:Usage–?ýGuide“for“distribution“objectsŽŽ¡¡‘8ïhtml:ï html:CHOOSING.A.GENERATORŽŽ¡’• "ïhtml:ï html:Notes–?ýon“choosing“a“generator“for“your“simŽŽ¡¡‘8ïhtml:ï html:DEFAULT.GENERATORSŽŽ¡’• "ïhtml:ï html:Default–?ýgenerators“invoked“by“distributionsŽŽ¡¡‘8ïhtml:ï html:SOURCES.for.0.7ŽŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹é 6ü “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ’•[ïhtml:ï html:¿Literature–?ýreferences“for“implemented“objectsŽŽ¤¡‘Kïhtml:ï html:doc.generators.tableŽŽ¡’•[ïhtml:ï html:Summary–?ýdescriptive“data“for“generatorsŽŽ¡¡‘Kïhtml:ï html:doc.generators.maxvalueŽŽ¡’•[ïhtml:ï html:Values–?ýreturned“by“[myGen“getUnsignedSample]ŽŽ¡¡‘Kïhtml:ï html:doc.quality.generatorsŽŽ¡’•[ïhtml:ï html:Results–?ýof“statistical“and“timing“testsŽŽ¡¡‘Kïhtml:ï html:doc.timingsŽŽ¡’•[ïhtml:ï html:Timing–?ýresults“for“generators“and“distributionsŽŽ¡¡‘Kïhtml:ï html:methods.SimpleGenerators.hŽŽ¡’•[ïhtml:ï html:Methods–?ýimplemented“by“a“typical“Simple“generatorŽŽ¡¡‘Kïhtml:ï html:methods.SplitGenerators.hŽŽ¡’•[ïhtml:ï html:Methods–?ýimplemented“by“a“typical“Split“generatorŽŽ¡¡ºâ© ïhtml:ï html:ïhtml:ï html:¡‘0¾Anyone–?ýwho“attempts“to“generate“random“numbers“by“deterministic“means“is,“of“course,Ž¡‘0living–?ýin“a“state“of“sin.‘ ú--‘¼r¿Jon“von“NeumanŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¡‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-08ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ê AW “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Random–/Library:‘m™P•Üorting“to“Random“0.7ŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤¿The–?ýchanges“from“version“0.6“to“0.7“consist“mostly“of“a“restructuring“of“the“implementationŽ¡of–?ýthe“library.‘ úHowever,“there“are“some“interface“changes,“as“well,“and“the“porting“of“applicationsŽ¡written–?ýto“work“with“the“0.6“version“ïhtml:ï html:might“require“changes“to“accomodate“the“new“interface.Ž¡Also,–?ýit“is“advised“that“you“take“a“look“at“the“new“interface,“regardless“of“whether“your“applicationŽ¡compiles–?ýand“runs“with“the“new“random“because“the“old“interface“is“deprecated“and“will“eventuallyŽ¡be–?ýremoved“and“because“some“of“the“functionality“of“the“library“changed“such“that“the“executionŽ¡of–?ýyour“application“may“differ.ŽŸ8äïhtml:ï html:ŸG®ïhtml:ï html:Ÿƒ†ÀMinimalist–QëP§Œorting“Notes:ŽŸ^5¿What–?ýis“described“here“is“the“minimum“a“normal“random“user“would“have“to“change“to“get“herŽ¡apps–?ýrunning“with“the“0.7.‘ úFor“complete“documentation“of“the“changes“made“to“the“random“library,Ž¡check–?ýthe“files:ŽŸ ^5ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¡É$(SWARMHOME)/src/random/docs/WHATS.CHANGED.in.0.7Ž©!#ïhtml:ï html:Ÿ ÞÝ¿andŽïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¡É$(SWARMHOME)/src/random/docs/WHATS.NEW.in.0.7Ž¦ïhtml:ï html:Ÿ ïhtml:ï html:©ïhtml:ï html:Ÿ ÞÝ‘0ïcolor push Black¿1.ï color popŽŽ‘<The–?ý'magic“numbers'“used“by“ïhtml:ï html:setState/getState“to“identify“generators“and“distributionsŽ¡‘<have–?ýchanged.‘ úThe“sizes“of“the“records“returned“by“ïhtml:ï html:getState“have“also“changed.Ž¡‘<Therefore–?ýversion“0.7“generators“will“refuse“to“ïhtml:ï html:setStatea“generator“based“on“versionŽ¡‘<0.6‘?ýdata.Ž¦ïhtml:ï html:¡‘0ïcolor push Black2.ï color popŽŽ‘<The–?ýïhtml:ï html:setState“method“has“been“renamed“to“ïhtml:ï html:setStateFrom,“and“ïhtml:ï html:getState“to“ïhtml:ï html:putStateInto.ŽŸ8äïhtml:ï html:© Ç‘0ïcolor push Black3.ï color popŽŽ‘<The–?ýïhtml:ï html:verifySelf“methods“have“been“exorcised.‘ úTheir“code“has“been“moved“to“a“separateŽ¡‘<test‘?ýprogram.ŽŸ8äïhtml:ï html:¦‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:¦‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ë Gø “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Random–/Library:‘m™Interface“Refer |enceŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤‡…‘0¿The–?ýïhtml:ï html:¾random‘üo¿library“uses“the“ïhtml:ï html:module“definition“conventionsïhtml:ï html:Ž¡‘0(../defobj/module.html)Ž¡‘0established–?ýby“the“ïhtml:ï html:ïhtml:ï html:¾defobj‘üo¿libraryïhtml:ï html:Ž¡‘0(../defobj.html)Ž¡‘0.‘ úIt–?ýalso“depends“on“standard“supertypes“and“classes“defined“by“this“library.ŽŸ€’ïhtml:ï html:ŸÀDependenciesŽŸåº¿Following–?ýare“the“other“header“files“imported“by“:ŽŸ—ïhtml:ï html:ïhtml:ï html:Ÿ N¡‘0Â#import‘ffŽ¤bÌïhtml:ï html:ïhtml:ï html:©$¹‘0#import‘ffŽ¡ïhtml:ï html:ïhtml:ï html:¦‘0#import‘ffŽ¡ïhtml:ï html:ïhtml:ï html:¦‘0#import‘ffŽ¡ïhtml:ï html:ïhtml:ï html:¦‘0#import‘ffŽŸbÌïhtml:ï html:¦‘0¿The–?ýïhtml:ï html:¾defobj‘üo¿library“interface“is“included“to“provide“the“basic“object“support.‘ úïhtml:ï html:ÂRan-ŽŸ‘0domDefs.h–?ý¿contains“some“C“preprocessor“macros“and“typedefs“used“in“the“library.ŽŸ‘0„¤ŽŽ¤G®ïhtml:ï html:©CïÀObject–QëT‘þ¸¦ypes“(with“links“to“r•°gefer“ence‘Qëpages)ŽŸ^5‘0„¤ŽŽ¡ïhtml:ï html:¦Contents:ŽŸ ¢Âïhtml:ï html:ŸBø‘0¿The–?ýfollowing“shows“the“protocol“inheritance“trees“and“object“definitions“for“generatorsŽ¤‘0and–?ýdistributions.‘ úThe“complete“set“of“methods“implemented“by“these“objects“haveŽ¡‘0been–?ýsubdivided“into“sub-protocols“of“methods“that“belong“together“logically.‘ úJustŽ¡‘0click–?ýon“a“(sub-)protocol“name“to“see“what“methods“it“implements.‘ ú(You“may“want“toŽ¡‘0review–?ýthe“section“on“Protocols“in“the“Objective-C“book“here!)Ž©8äïhtml:ï html:Ÿ N¡‘0In–?ýthe“list“below,“any“line“that“contains“the“word“CREATABLE“defines“an“object“thatŽ¡‘0you–?ýcan“use“in“your“program.› ú(This“is“part“of“the“Swarm“DefObj“machinery.)˜In“otherŽ¡‘0words,–?ýwhile“'InternalState'“is“a“normal“protocol“(a“list“of“method“definitions),Ž¡‘0the–?ýname“'ACGgen'“refers“to“both“a“protocol“and“a“class“that“implements“that“protocol.Ž¡‘0(You–?ýcreate“an“ACG“generator“by“saying“myGen“=“[ACGgen“create:– ú....]).“Similarly,Ž¡‘0'GammaDist'–?ýdefines“both“a“protocol“and“a“class“that“implements“that“protocol.Ž¦ïhtml:ï html:Ÿ N¡‘0All–?ýgenerators“and“distributions“ultimately“inherit“from“SwarmObject.Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ì SÕ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿The–?ýtwo“files“'methods.SimpleGenerators.h'“and“'methods.SplitGenerators.h'“in“directoryŽ¤‘/ºâ/random/docs–?ýshow“the“complete“sets“of“methods“implemented“for“the“two“most“commonŽ¡‘/ºâtypes–?ýof“generator.Žºâ©8äïhtml:ï html:Ÿffïhtml:ï html:Ÿ=ÅGeneratorsŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:Ÿõ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿InternalStateïhtml:ï html:Ž¤.:‘0(Prot.html#InternalState)ŽŸÕSïhtml:ï html:ŸXç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SingleSeedïhtml:ï html:Ž¡‘0(Prot.html#SingleSeed)Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿MultiSeedïhtml:ï html:Ž¡‘0(Prot.html#MultiSeed)ŽŸÕSïhtml:ï html:ŸXç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Simpleïhtml:ï html:Ž¡‘0(Prot.html#Simple)Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SimpleOutïhtml:ï html:Ž¡‘0(Prot.html#SimpleOut)Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SplitSingleSeedïhtml:ï html:Ž¡‘0(Prot.html#SplitSingleSeed)Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SplitMultiSeedïhtml:ï html:Ž¡‘0(Prot.html#SplitMultiSeed)Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Splitïhtml:ï html:Ž¡‘0(Prot.html#Split)Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SplitOutïhtml:ï html:Ž¡‘0(Prot.html#SplitOut)Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SingleShortGeneratorïhtml:ï html:Ž¡‘0(Prot.html#SingleShortGen)Ž¡‘0Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SingleLongGeneratorïhtml:ï html:Ž¡‘0(Prot.html#SingleLongGen)Ž¡‘0Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿CombinedShortGeneratorïhtml:ï html:Ž¡‘0(Prot.html#CombinedShortGen)Ž¡‘0Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿CombinedLongGeneratorïhtml:ï html:Ž¡‘0(Prot.html#CombinedLongGen)Ž¡‘0Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SingleShortSplitGeneratorïhtml:ï html:Ž¡‘0(Prot.html#SingleShortSplitGen)Ž¡‘0Ž¦ïhtml:ï html:Ÿ õV‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SingleLongSplitGeneratorïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹í ` “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ¿(Prot.html#SingleLongSplitGen)Ž¤‘/ºâŽºâ©8äïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿CombinedShortSplitGeneratorïhtml:ï html:Ž¡‘0(Prot.html#CombinedShortSplitGen)Ž¡‘0Ž¦ïhtml:ï html:© Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿CombinedLongSplitGeneratorïhtml:ï html:Ž¡‘0(Prot.html#CombinedLongSplitGen)Ž¡‘0ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ACGgenïhtml:ï html:Ž¡‘0(ACGgen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿C2LCGXgenïhtml:ï html:Ž¡‘0(C2LCGXgen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿C2MRG3genïhtml:ï html:Ž¡‘0(C2MRG3gen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿C2TAUSgenïhtml:ï html:Ž¡‘0(C2TAUS1-3gen.html)Ž¡‘0ŽŸcïhtml:ï html:Ÿïhtml:ï html:Ÿ œs‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿C2TAUS1genïhtml:ï html:Ž¡‘:(C2TAUS1-3gen.html#C2TAUS1gen)Ž¡‘::‘ úC2TAUSgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿C2TAUS2genïhtml:ï html:Ž¡‘:(C2TAUS1-3gen.html#C2TAUS2gen)Ž¡‘::‘ úC2TAUSgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿C2TAUS3genïhtml:ï html:Ž¡‘:(C2TAUS1-3gen.html#C2TAUS3gen)Ž¡‘::‘ úC2TAUSgen–?ýŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿C3MWCgenïhtml:ï html:Ž¡‘0(C3MWCgen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿C4LCGXgenïhtml:ï html:Ž¡‘0(C4LCGXgen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿LCGgenïhtml:ï html:Ž¡‘0(LCG1-3gen.html)Ž¡‘0ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿LCG1genïhtml:ï html:Ž¡‘:(LCG1-3gen.html#LCG1gen)Ž¡‘::‘ úLCGgen–?ýŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹î nÛ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿LCG2genïhtml:ï html:Ž¤-ó‘:(LCG1-3gen.html#LCG2gen)Ž¡‘::‘ úLCGgen–?ýŽŸ8äïhtml:ï html:© õ‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿LCG3genïhtml:ï html:Ž¡‘:(LCG1-3gen.html#LCG3gen)Ž¡‘::‘ úLCGgen–?ýŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿MRGgenïhtml:ï html:Ž¡‘0(MRG5-7gen.html)Ž¡‘0ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿MRG5genïhtml:ï html:Ž¡‘:(MRG5-7gen.html#MRG5gen)Ž¡‘::‘ úMRGgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿MRG6genïhtml:ï html:Ž¡‘:(MRG5-7gen.html#MRG6gen)Ž¡‘::‘ úMRGgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿MRG7genïhtml:ï html:Ž¡‘:(MRG5-7gen.html#MRG7gen)Ž¡‘::‘ úMRGgen–?ýŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿MT19937genïhtml:ï html:Ž¡‘0(MT19937gen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿MWCAgenïhtml:ï html:Ž¡‘0(MWCA-Bgen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿MWCBgenïhtml:ï html:Ž¡‘0(MWCA-Bgen.html#MWCBgen)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿PMMLCGgenïhtml:ï html:Ž¡‘0(PMMLCG1-9gen.html)Ž¡‘0ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG1genïhtml:ï html:Ž¡‘:(PMMLCG1-9gen.html#PMMLCG1gen)Ž¡‘::‘ úPMMLCGgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG2genïhtml:ï html:Ž¡‘:(PMMLCG1-9gen.html#PMMLCG2gen)Ž¡‘::‘ úPMMLCGgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG3genïhtml:ï html:Ž¡‘:(PMMLCG1-9gen.html#PMMLCG3gen)Ž¡‘::‘ úPMMLCGgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG4genïhtml:ï html:ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ï | “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘9ºâ¿(PMMLCG1-9gen.html#PMMLCG4gen)Ž¤ ‘9ºâ:‘ úPMMLCGgen–?ýŽºâ©8äïhtml:ï html:Ÿ ç‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG5genïhtml:ï html:Ž¡‘:(PMMLCG1-9gen.html#PMMLCG5gen)Ž¡‘::‘ úPMMLCGgen–?ýŽ¦ïhtml:ï html:Ÿ ç‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG6genïhtml:ï html:Ž¡‘:(PMMLCG1-9gen.html#PMMLCG6gen)Ž¡‘::‘ úPMMLCGgen–?ýŽ¦ïhtml:ï html:Ÿ ç‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG7genïhtml:ï html:Ž¡‘:(PMMLCG1-9gen.html#PMMLCG7gen)Ž¡‘::‘ úPMMLCGgen–?ýŽ¦ïhtml:ï html:Ÿ ç‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG8genïhtml:ï html:Ž¡‘:(PMMLCG1-9gen.html#PMMLCG8gen)Ž¡‘::‘ úPMMLCGgen–?ýŽ¦ïhtml:ï html:© ç‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿PMMLCG9genïhtml:ï html:Ž¡‘:(PMMLCG1-9gen.html#PMMLCG9gen)Ž¡‘::‘ úPMMLCGgen–?ýŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿PSWBgenïhtml:ï html:Ž¡‘0(PSWBgen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿RWC2genïhtml:ï html:Ž¡‘0(RWC28gen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿RWC8genïhtml:ï html:Ž¡‘0(RWC28gen.html#RWC8gen)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SCGgenïhtml:ï html:Ž¡‘0(SCGgen.html)Ž¡‘0ŽŸ8äïhtml:ï html:¦‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿SWBgenïhtml:ï html:Ž¡‘0(SWB1-3gen.html)Ž¡‘0ŽŸ8äïhtml:ï html:Ÿïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿SWB1genïhtml:ï html:Ž¡‘:(SWB1-3gen.html#SWB1gen)Ž¡‘::‘ úSWBgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿SWB2genïhtml:ï html:Ž¡‘:(SWB1-3gen.html#SWB2gen)Ž¡‘::‘ úSWBgen–?ýŽŸ8äïhtml:ï html:¦‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿SWB3genïhtml:ï html:Ž¡‘:(SWB1-3gen.html#SWB3gen)Ž¡‘::‘ úSWBgen–?ýŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ð ‰Õ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿TGFSRgenïhtml:ï html:Ž¤"‘0(TGFSRgen.html)Ž¡‘0Ž©8äïhtml:ï html:Ÿïhtml:ï html:Ÿ é:‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿TT403genïhtml:ï html:Ž¡‘:(TGFSRgen.html#TT403gen)Ž¡‘::‘ úTGFSRgen–?ýŽ¦ïhtml:ï html:Ÿ é:‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿TT775genïhtml:ï html:Ž¡‘:(TGFSRgen.html#TT775gen)Ž¡‘::‘ úTGFSRgen–?ýŽ¦ïhtml:ï html:Ÿ é:‘:ïcolor push BlackÌlï color popŽŽ‘Dïhtml:ï html:¿TT800genïhtml:ï html:Ž¡‘:(TGFSRgen.html#TT800gen)Ž¡‘::‘ úTGFSRgen–?ýŽŸ8äïhtml:ï html:Ÿffïhtml:ï html:Ÿ0èÅDistrib¶JutionsŽŸ 9 ïhtml:ï html:Ÿïhtml:ï html:Ÿèþ‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ProbabilityDistributionïhtml:ï html:Ž¡‘0(Prot.html#ProbabilityDist)Ž¡‘0Ž¦ïhtml:ï html:Ÿ é:‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿BooleanDistributionïhtml:ï html:Ž¡‘0(Prot.html#BooleanDistribution)Ž¡‘0Ž¦ïhtml:ï html:Ÿ é:‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿IntegerDistributionïhtml:ï html:Ž¡‘0(Prot.html#IntegerDistribution)Ž¡‘0Ž¦ïhtml:ï html:Ÿ é:‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿UnsignedDistributionïhtml:ï html:Ž¡‘0(Prot.html#UnsignedDistribution)Ž¡‘0Ž¦ïhtml:ï html:Ÿ é:‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿DoubleDistributionïhtml:ï html:Ž¡‘0(Prot.html#DoubleDistribution)Ž¡‘0Ž¦ïhtml:ï html:Ÿ é:‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿Normalïhtml:ï html:Ž¡‘0(Prot.html#Normal)Ž¡‘0ŽŸïhtml:ï html:¡‘0ïcolor push BlackÁlï color popŽŽŽž¬ïhtml:ï html:ïhtml:ï html:Ÿr‘:¿RandomBitDistïhtml:ï html:Ž¡‘:(RandomBitDist.html)Ž¡‘:Ž©cïhtml:ï html:Ÿ ¾‘‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿BernoulliDistïhtml:ï html:Ž¡‘0(BernoulliDist.html)Ž¡‘0Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ñ –Ã “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâïcolor push BlackÁlï color popŽŽ‘9ºâïhtml:ï html:¿UniformIntegerDistïhtml:ï html:Ž¤‘/ºâ(UniformIntegerDist.html)Ž¡‘/ºâŽºâ©8äïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿UniformUnsignedDistïhtml:ï html:Ž¡‘0(UniformUnsignedDist.html)Ž¡‘0Ž¦ïhtml:ï html:Ÿ Ç‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿UniformDoubleDistïhtml:ï html:Ž¡‘0(UniformDoubleDist.html)Ž¡‘0Ž©cïhtml:ï html:Ÿ œs‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿ExponentialDistïhtml:ï html:Ž¡‘0(ExponentialDist.html)Ž¡‘0Ž¦ïhtml:ï html:Ÿ œs‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿GammaDistïhtml:ï html:Ž¡‘0(GammaDist.html)Ž¡‘0Ž¦ïhtml:ï html:Ÿ œs‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿NormalDistïhtml:ï html:Ž¡‘0(NormalDist.html)Ž¡‘0Ž¦ïhtml:ï html:Ÿ œs‘0ïcolor push BlackÁlï color popŽŽ‘:ïhtml:ï html:¿LogNormalDistïhtml:ï html:Ž¡‘0(NormalDist.html#LogNormalDist)Ž¡‘0Ž©‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(../random.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRïï html:¦(../random.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(UsageGuide.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ò £U “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Random–/Library:‘m™Prš |otocol“Refer˜enceŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¤Lr‘0¿InternalStateïhtml:ï html:ŽŸïhtml:ï html:¡‘0Â//Ž¡‘0//–ffInternalState“--Ž¡‘0//‘32Methods–ffto“save“the“internal“state“of“an“object“(genera-Ž©‘0tor,‘ffdistribution)Ž¡‘0//‘32to–ffa“memory“buffer“allocated“by“the“calling“pro-Ž¦‘0gram,–ffand“to“set“the“stateŽ¡‘0//‘32of–ffan“object“from“previously“saved“state“data,“provided“in“a“mem-Ž¦‘0ory‘ffbuffer.Ž¡‘0//‘32Method–ff-getStateSize“specifies“the“minimum“buffer“size“needed.Ž¡‘0//Ž¡‘0@protocol‘ffInternalStateŽ¡‘0-–ff(unsigned)“getStateSize;“//“size“of“buffer“neededŽ¡‘0-–ff(void)“putStateInto:“(void“*)“buffer;“//“save“state“data“for“later“useŽ¡‘0-–ff(void)“setStateFrom:“(void“*)“buffer;“//“set“state“from“saved“dataŽ¡‘0-–ff(void)“describe:“(id)“outStream;“//“prints“ascii“data“to“streamŽ¡‘0-–ff(char“*)‘ fdgetName;“//“returns“name“of“objectŽ¡‘0-–ff(unsigned)“getMagic;“//“object's“'magic“number'Ž¡‘0@endŽŸ‘0„¤ŽŽŸ ïhtml:ï html:¡‘0¿The–?ýïhtml:ï html:InternalState“protocol“provides“attributes“common“to“the“generators“and“distributionsŽ¦‘0provided–?ýin“the“ïhtml:ï html:random“library.‘ úThis“protocol“could“be“used“for“any“class“of“objectsŽ¦‘0that–?ýmight“contain“an“internal“state,“including“things“unrelated“to“pseudo“randomŽ¦‘0number‘?ýgeneration.ŽŸ8äïhtml:ï html:Ÿ Ž‘0The–?ý"state"“of“a“given“object“depends“on“the“type“of“object“it“is.‘ úIn“the“case“ofŽ¦‘0ïhtml:ï html:random,–?ýboth“the“bit“generators“and“the“distributions“are“capable“of“carrying“state.Ž¦‘0The–?ýstate“is,“in“all“cases,“a“structure“that“is“understood“by“the“object“with“whichŽ¦‘0it–?ýis“associated.‘ úThe“details“of“this“structure“can“be“found“in“the“code“for“theŽ¦‘0given–?ýgenerator“or“distribution;“but,“in“general,“the“user“is“not“expected“to“understandŽ¦‘0the–?ýstructure.‘ úWhere“the“state“must“be“saved“and“used“to“restart,“the“user“is“expectedŽ¦‘0only–?ýto“read“and“write“the“block“of“memory“from“and“to“the“disk“and“pass“the“pointerŽ¦‘0to–?ýand“from“the“object“with“which“the“state“is“associated.‘ ú[See“the“ïhtml:ï html:Usage“Guideïhtml:ï html:Ž¡‘0(./UsageGuide.html)Ž¡‘0for–?ýexamples“of“how“to“do“this.]‘ úPlease“note“that“different“computer“architecturesŽ¦‘0store–?ýbinary“data“in“memory“in“different“ways“(using“different“byte“orders).‘ úSinceŽ¦‘0this–?ýversion“of“the“ïhtml:ï html:InternalState“protocol“stores“data“in“binary“form,“you“ïhtml:ï html:cannotŽ¦‘0expect–?ýto“be“able“to“use“these“methods“to“transfer“data“between“different“computers.Ž¦‘0We–?ýhope“to“lift“this“restriction“in“a“future“version.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ Ž‘0(unsigned)–?ý-getStateSize“returns“an“unsigned“integer“indicating“how“many“bytes“ofŽ¦‘0memory–?ýare“necessary“to“save“the“state“of“the“object.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ó l “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ïhtml:ï html:© ‘0¿(void)–?ý-getState:‘ ú(void“*)“state“writes“a“copy“of“the“state“of“the“object“into“theŽ¤‘0memory–?ýaddress“pointed“to“by“the“"state"“pointer“passed“to“it.‘ úThe“memory“shouldŽ¡‘0be–?ýallocated“before“the“message“is“sent.ŽŸ8äïhtml:ï html:ïhtml:ï html:Ÿ P‘0(void)–?ý-setState:‘ ú(void“*)“state“copies“the“values“contained“in“the“memory“addressŽ¡‘0pointed–?ýto“by“"state"“into“the“state“variables“used“by“the“object.‘ úThe“block“of“memoryŽ¡‘0containing–?ýthe“state“may“be“sent“back“to“the“heap“after“the“message“has“been“sent.ŽŸ‘0„¤ŽŽ¦ïhtml:ï html:¤\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¦ïhtml:ï html:Ÿ:4(./Interface.html)ŽŸÕSïhtml:ï html:¡’áøRïï html:Ÿ:4(./Interface.html)ŽŸÕSïhtml:ï html:¡’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¦ïhtml:ï html:Ÿ ‘0„¤ŽŽ¦ïhtml:ï html:¤:4‘0These–?ýdescriptions“are“not“finished.‘ úPlease“see“the“documentation“in“ïhtml:ï html:Â$(SWARMHOME)/src/random/docs/ŽŸ‘0„¤ŽŽŸ¼jïhtml:ï html:Ÿ@½Generator‘/Pr |otocolsŽŸÃjïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿçñ‘0¿SingleSeedïhtml:ï html:ŽŸ8äïhtml:ï html:Ÿ P‘0Â@deftype‘ffSingleSeedŽ¡‘0CREATINGŽ¡‘0+‘ ÌÌcreate:–ffaZone“setStateFromSeed:“(unsigned)“seed;Ž¡‘0USINGŽ¡‘0-‘ffsetStateFromSeed:‘ ÌÌ(unsigned)‘32seed;Ž¡‘0-–ff(unsigned)“getMaxSeedValue;Ž¡‘0-‘ff(unsigned)‘ ÌÌgetInitialSeed;Ž¡‘0@endŽŸÉïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿk‘0¿MultiSeedïhtml:ï html:ŽŸïhtml:ï html:¡‘0Â@deftype‘ffMultiSeedŽ¡‘0CREATINGŽ¡‘0+–ffcreate:“aZone“setStateFromSeeds:“(unsigned“*)“seeds;ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ô ºå “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂUSINGŽ¤Ð‘/ºâ-–ffsetStateFromSeeds:“(unsigned“*)“seeds;Ž¡‘/ºâ-‘ff(unsigned)‘ ÌÌlengthOfSeedVector;Ž¡‘/ºâ-–ff(unsigned“*)“getMaxSeedValues;Ž¡‘/ºâ-–ff(unsigned“*)‘ ÌÌgetInitialSeeds;Ž¡‘/ºâ@endŽºâ©Éïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿû‘0¿Simpleïhtml:ï html:ŽŸ8äïhtml:ï html:Ÿ Þì‘0Â@deftype‘ffSimpleŽ¡‘0CREATINGŽ¡‘0+–ffcreateWithDefaults:“aZone;Ž¡‘0USINGŽ¡‘0-–ffsetAntithetic:“(BOOL)“antiT;Ž¡‘0-–ff(BOOL)“getAntithetic;Ž¡‘0-–ff(unsigned“long“long“int)“getCurrentCount;Ž¡‘0@endŽ¦ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿû‘0¿SimpleOutïhtml:ï html:ŽŸ8äïhtml:ï html:Ÿ Þì‘0Â@deftype‘ffSimpleOutŽ¡‘0USINGŽ¡‘0-‘ff(unsigned)‘™˜getUnsignedMax;Ž¡‘0-–ff(unsigned)“getUnsignedSample;Ž¡‘0-–ff(float)‘%ÌÊgetFloatSample;“//“using“1“unsignedŽ¡‘0-–ff(double)‘ fdgetThinDoubleSample;“//“using“1“unsignedŽ¡‘0-–ff(double)‘ fdgetDoubleSample;“//“using“2“unsignedsŽ¡‘0-–ff(long“double)“getLongDoubleSample;“//“using“2“unsignedsŽ¡‘0@endŽ¦ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿû‘0¿SplitSingleSeedïhtml:ï html:ŽŸ8äïhtml:ï html:Ÿ Þì‘0Â@deftype‘ffSplitSingleSeedŽ¡‘0CREATINGŽ¡‘0+–ffcreate:“aZoneŽ¡‘@32setA:–ff(unsigned)“A‘ ÌÌ//“#“of“virtual“generatorsŽ¡‘@32setv:–ff(unsigned)“v‘ ÌÌ//“log2(#segments/generator)Ž¡‘@32setw:–ff(unsigned)“w“//“log2(segment“length)Ž¡‘0setStateFromSeed:–ff(unsigned)“seed;Ž¡‘0USINGŽ¡‘0-–ffsetStateFromSeed:“(unsigned)“seed;Ž¡‘0-–ff(unsigned)“getMaxSeedValue;Ž¡‘0-–ff(unsigned)“getInitialSeed;Ž¡‘0@endŽ¦ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿû‘0¿SplitMultiSeedïhtml:ï html:ŽŸ8äïhtml:ï html:Ÿ Þì‘0Â@deftype‘ffSplitMultiSeedŽ¡‘0CREATINGŽ¡‘0+–ffcreate:“aZoneŽ¡‘@32setA:–ff(unsigned)“A‘ ÌÌ//“#“of“virtual“generatorsŽ¡‘@32setv:–ff(unsigned)“v‘ ÌÌ//“log2(#segments/generator)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹õ Ä7 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘?îÂsetw:–ff(unsigned)“w“//“log2(segment“length)Ž¤ •‘/ºâsetStateFromSeeds:–ff(unsigned“*)“seeds;Ž¡‘/ºâUSINGŽ¡‘/ºâ-–ffsetStateFromSeeds:“(unsigned“*)“seeds;Ž¡‘/ºâ-‘ff(unsigned)‘ ÌÌlengthOfSeedVector;Ž¡‘/ºâ-–ff(unsigned“*)“getMaxSeedValues;“//“min“is“1Ž¡‘/ºâ-–ff(unsigned“*)“getInitialSeeds;“//“=“getInitialSeeds:“0Ž¡‘/ºâ@endŽºâ©Éïhtml:ï html:ïhtml:ï html:ïhtml:ï html:ŸíÌ‘0¿Splitïhtml:ï html:ŽŸ8äïhtml:ï html:Ÿ Ñ±‘0Â@deftype‘ffSplitŽ¡‘0CREATINGŽ¡‘0+–ffcreateWithDefaults:“aZone;Ž¡‘0USINGŽ¡‘0-–ffsetAntithetic:“(BOOL)“antiT;Ž¡‘0-–ff(unsigned)‘™˜getNumGenerators;“//“returns“AŽ¡‘0-–ff(unsigned)‘™˜getNumSegments;“//“returns“vŽ¡‘0-–ff(unsigned)‘™˜getSegmentLength;“//“returns“wŽ¡‘0-–ff(BOOL)“getAntithetic;Ž¡‘0-–ffinitGenerator:‘™˜(unsigned)“vGen;“//“to“segment“#0Ž¡‘0-–ffrestartGenerator:“(unsigned)“vGen;“//“start“of“current“segmentŽ¡‘0-–ffadvanceGenerator:“(unsigned)“vGen;“//“to“next“segmentŽ¡‘0-–ffjumpGenerator:‘™˜(unsigned)“vGen‘ ÌÌtoSegment:“(unsigned“long“long“int)“seg;Ž¡‘0-–ffinitAll;“//“to“segment“#0Ž¡‘0-–ffrestartAll;“//“start“of“current“segmentŽ¡‘0-–ffadvanceAll;“//“to“next“segmentŽ¡‘0-–ffjumpAllToSegment:“(unsigned“long“long“int)“seg;Ž¡‘0-–ff(unsigned“long“long“int)“getCurrentCount:‘32(unsigned)“vGen;Ž¡‘0-–ff(unsigned“long“long“int)“getCurrentSegment:“(unsigned)“vGen;Ž¡‘0@endŽ¦ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:ŸíÌ‘0¿SplitOutïhtml:ï html:ŽŸ8äïhtml:ï html:Ÿ Ñ±‘0Â@deftype‘ffSplitOutŽ¡‘0USINGŽ¡‘0-‘ff(unsigned)‘™˜getUnsignedMax;Ž¡‘0-–ff(unsigned)“getUnsignedSample:‘32(unsigned)“vGen;Ž¡‘0-–ff(float)‘%ÌÊgetFloatSample:‘ fd(unsigned)“vGen;“//“using“1“unsignedŽ¡‘0-–ff(double)‘ fdgetThinDoubleSample:“(unsigned)“vGen;“//“using“1“unsignedŽ¡‘0-–ff(double)‘ fdgetDoubleSample:‘ÿþ(unsigned)“vGen;“//“using“2“unsignedsŽ¡‘0-–ff(long“double)“getLongDoubleSample:“(unsigned)“vGen;“//“using“2“unsignedsŽ¡‘0@endŽ¦ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:ŸíÌ‘0¿SingleShortGeneratorïhtml:ï html:Ž¡‘0Ž©8äïhtml:ï html:Ÿ Ñ±‘0ÂNo–ffextra“messages“added.ŽŸbÌïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿ §É‘0¿SingleLongGeneratorïhtml:ï html:Ž¡‘0Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ö Í’ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂNo–ffextra“messages“added.Žºâ¤bÌïhtml:ï html:ïhtml:ï html:ïhtml:ï html:© Ïõ‘0¿CombinedShortGeneratorïhtml:ï html:ŽŸ2Á‘0ŽŸ8äïhtml:ï html:Ÿ ùÝ‘0ÂNo–ffextra“messages“added.Ž¡ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¦‘0¿CombinedLongGeneratorïhtml:ï html:ŽŸ2Á‘0ŽŸ8äïhtml:ï html:Ÿ ùÝ‘0ÂNo–ffextra“messages“added.Ž¡ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¦‘0¿SingleShortSplitGeneratorïhtml:ï html:ŽŸ2Á‘0ŽŸ8äïhtml:ï html:Ÿ ùÝ‘0ÂNo–ffextra“messages“added.Ž¡ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¦‘0¿SingleLongSplitGeneratorïhtml:ï html:ŽŸ2Á‘0ŽŸ8äïhtml:ï html:Ÿ ùÝ‘0ÂNo–ffextra“messages“added.Ž¡ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¦‘0¿CombinedShortSplitGeneratorïhtml:ï html:ŽŸ2Á‘0ŽŸ8äïhtml:ï html:Ÿ ùÝ‘0ÂNo–ffextra“messages“added.Ž¡ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:¦‘0¿CombinedLongSplitGeneratorïhtml:ï html:Ž¤2Á‘0Ž©8äïhtml:ï html:Ÿ ùÝ‘0ÂNo–ffextra“messages“added.ŽŸ‘0„¤ŽŽŸ¼jïhtml:ï html:ŸÍ½Distrib•Üution‘/Pr |otocolsŽŸÃjïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿà~‘0¿ProbabilityDistributionïhtml:ï html:Ž¡‘0Ž¦ïhtml:ï html:Ÿ ùÝ‘0Â//–ffProbabilityDistribution“--Ž¡‘0//Ž¡‘0//–ffA“process“for“generating“a“sequence“of“random“numbers“matching“theŽ¡‘0//‘32frequencies–ffdefined“by“a“specific“distribution“function.‘ ÌÌTheŽ¡‘0//‘32process–ffis“driven“by“input“from“a“supplied“uniform“random“generator.Ž¡‘0//Ž¡‘0@deftype–ffProbabilityDistribution“Ž¡‘0CREATINGŽ¡‘0+–ffcreateWithDefaults:“aZone;Ž¡‘0+–ffcreate:“aZone“setGenerator:“(id)“generator;Ž¡‘0+–ffcreate:“aZone“setGenerator:“(id)“generatorŽ¡‘0setVirtualGenerator:–ff(unsigned)“vGen;Ž¡‘0+‘ffcreateBegin;Ž¡‘0USINGŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹÷ Øü “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ-–ffsetGenerator:“(id)“generator;Ž¤b‘/ºâ-–ffsetGenerator:“(id)“generatorŽ¡‘/ºâsetVirtualGenerator:–ff(unsigned)“vGen;Ž¡‘/ºâ-‘ffcreateEnd;Ž¡‘/ºâ-‘ffreset;Ž¡‘/ºâ-‘PÿúgetGenerator;Ž¡‘/ºâ-–ff(unsigned)“getVirtualGenerator;Ž¡‘/ºâ-–ff(BOOL)“getOptionsInitialized;Ž¡‘/ºâ-–ff(unsigned“long“long“int)“getCurrentCount;Ž¡‘/ºâ@endŽºâ©Éïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿû™‘0¿BooleanDistributionïhtml:ï html:Ž¡‘0ŽŸ8äïhtml:ï html:Ÿ ß~‘0Â//Ž¡‘0//–ffBooleanDistribution“--Ž¡‘0//‘32A–ffprobability“distribution“that“returns“YES/NO“sample“values.Ž¡‘0//Ž¡‘0@deftype–ffBooleanDistribution“Ž¡‘0-–ff(BOOL)“getBooleanSample;Ž¡‘0-–ff(int)“getIntegerSample;“//“for“convenienceŽ¡‘0@endŽ¦ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿû™‘0¿IntegerDistributionïhtml:ï html:Ž¡‘0ŽŸ8äïhtml:ï html:Ÿ ß~‘0Â//Ž¡‘0//–ffIntegerDistribution“--Ž¡‘0//‘32A–ffprobability“distribution“that“returns“integer“sample“values.Ž¡‘0//Ž¡‘0@deftype–ffIntegerDistribution“Ž¡‘0-–ff(int)“getIntegerSample;Ž¡‘0@endŽ¦ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿû™‘0¿UnsignedDistributionïhtml:ï html:Ž¡‘0ŽŸ8äïhtml:ï html:Ÿ ß~‘0Â//Ž¡‘0//–ffUnsignedDistribution“--Ž¡‘0//‘32A–ffprobability“distribution“that“returns“non-ŽŸ‘0negative–ffinteger“sample“values.Ž¡‘0//Ž¡‘0@deftype–ffUnsignedDistribution“Ž¡‘0-–ff(unsigned)“getUnsignedSample;Ž¡‘0@endŽ¦ïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿû™‘0¿DoubleDistributionïhtml:ï html:Ž¡‘0ŽŸ8äïhtml:ï html:Ÿ ß~‘0Â//Ž¡‘0//–ffDoubleDistribution“--Ž¡‘0//‘32A–ffprobability“distribution“that“returns“an“approximation“of“continuousŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ø å “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ//‘32values–ffas“represented“by“double-precision“floating“point“values.Ž¤‘/ºâ//Ž¡‘/ºâ@deftype–ffDoubleDistribution“Ž¡‘/ºâ-–ff(double)“getDoubleSample;Ž¡‘/ºâ@endŽºâŸÉïhtml:ï html:ïhtml:ï html:ïhtml:ï html:Ÿã7‘0¿Normalïhtml:ï html:Ž¡‘0ŽŸïhtml:ï html:¡‘0Â//Ž¡‘0//–ffNormalDistribution“--“a“well-known“continuous“probability“distributionŽ¡‘0//–ffLogNormalDistribution“--“also“well-known“...Ž¡‘0//Ž¡‘0@deftype–ffNormal“Ž¡‘0CREATINGŽ¡‘0+–ffcreate:“aZone“setGenerator:“generatorŽ¡’†f`setMean:–ff(double)“mean“setVariance:“(double)“variance;Ž¡‘0+–ffcreate:“aZone“setGenerator:“generatorŽ¡‘0setVirtualGenerator:–ff(unsigned)“vGenŽ¡’†f`setMean:–ff(double)“mean“setVariance:“(double)“variance;Ž¡‘0USINGŽ¡‘0-–ffsetMean:“(double)“mean“setVariance:“(double)“variance;Ž¡‘0-–ff(double)“getMean;Ž¡‘0-–ff(double)“getVariance;Ž¡‘0-–ff(double)“getStdDev;Ž¡‘0-–ff(double)“getSampleWithMean:“(double)“meanŽ¡‘0withVariance:–ff(double)“variance;Ž¡‘0@endŽ©‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRïï html:¦¿(./Interface.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ù îŠ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½A‘þÜCGgen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤"£‘0Â//Ž¡‘0//‘ffACGgen--Ž¡‘0//‘32predefined–ffrandom“number“generators,“not“recommended“for“serious“use;Ž¡‘0//‘32included–fffor“historical“reasons“(compatibility“with“earlier“releases).Ž¡‘0//Ž¡‘0@protocol–ffACGgen‘ fd“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:Ÿß ÀUse–Qëof“this“generator“is“ïhtml:ï html:NO‘ÿOT“RecommendedŽŸËÜïhtml:ï html:ŸZßDocumentationŽŸ ¢Âïhtml:ï html:ŸÞ‘0ÂGenerator–ffname:‘ ÌÌ|“ACGŽ¡¡‘0Description:‘ ÌÌ|–ffAdditive“Congruential“GeneratorŽ¡¡‘0Reference:‘ ÌÌ|–ffACG“is“an“often“used“algorithm,“mentioned“in“Knuth,Ž¡‘0|–ffNumerical“Recipes,“etc.Ž¡¡‘0|–ffstate“vector“=“f(seed)Ž¡‘0Algorithm:‘ ÌÌ|–ffstate_n“=“(state_(n-s)“+“state_(n-r))“mod“2^32;“r“>“sŽ¡‘0|–ffoutput“=“state_nŽ¡¡‘0|–ffACG“is“in“the“Lagged“Fibonacci“class“of“generators.Ž¡‘0|–ffThese“generators“use“a“basic“algorithm“of“the“formŽ¡‘0|–ffX_n“=“f(X_(n-r),X_(n-s))“mod“m;“r>sŽ¡‘0|–ffThe“function“f“is“typically“xor,“addition,“subtraction,Ž¡‘0|–ffmultiplication“or“subtraction“with“carry.“It“usesŽ¡‘0|–ffsimpler“math“than“a“basic“LCG,“but“keeps“a“larger“state.Ž¡¡‘0Comments:‘ ÌÌ|–ffThis“generator“relies“on“controlled“overflow“at“32“bits.Ž¡‘0|–ffThis“requires“that“unsigned“be“a“32bit“value“that“followsŽ¡‘0|–ffANSI“C“rules.Ž¡¡‘0Implementation:‘ ÌÌ|–ffThe“state“vector“contains“the“generator's“r“most“recentŽ¡‘0|–ffoutputs“(X_n“..“X_(n-r)).“This“vector“is“initialized“fromŽ¡‘0|–ffan“LCG“generator“using“one“32-bit“seed“value.“AfterŽ¡‘0|–ffinitialization“we“throw“away“r*5“numbers“to“'prime'“theŽ¡‘0|–ffgenerator“(i.e.“make“sure“we“have“entered“a“closed“cycle.)Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ú õÊ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂParameters:‘ ÌÌ|–ffunsigned“int“r“//“long“lagŽ¤.Œ‘/ºâ|–ffunsigned“int“s“//“short“lagŽ¡¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“state[r]“//“state“vectorŽ¡¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,2^32-1]“may“be“returnedŽ¡‘/ºâ|–ff(i.e.“[0,4294967295].)Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“[1,2^32-2]Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“these“generatorsŽ¡‘/ºâ|–ffhave“a“cycle“of“length“about“2^r.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Low“order“bits“are“poor,“and“there“are“other“problems.Ž¡‘/ºâ|–ffSWB“is“a“better“generator“in“the“same“class,“and“it“isŽ¡‘/ºâ|–ffonly“slightly“slower.Ž¡¡‘/ºâReference–fffor“|“Knuth,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâACGgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*2.702‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–4.482“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“8.299“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“1.369“(time“0.731)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff|“-----------------------------------------------------------Ž¦‘/ºâ---Ž¡¡‘/ºâParameters:‘ ÌÌ|–ffr“=“55Ž¡‘/ºâ|–ffs“=“24Ž¡¡‘/ºâReference–fffor“|“These“values“recommended“by“Knuth.Ž¡‘/ºâparameters:‘ ÌÌ|Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“length“~“2^r.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Low-order“bits“are“poor.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹û ýë “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤‘/ºâÂReference–fffor“|“Knuth,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦¿(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRïï html:¦(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(./C2LCGXgen.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ü “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½C2LCGXgen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffC2LCGX“--Ž¡‘0//‘32short–ffcomponent“based“generator“with“splitting“facilities.“Recommended.Ž¡‘0//Ž¡‘0@deftype–ffC2LCGXgen‘ ÌÌ“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“C2LCGXŽ¡¡‘0Description:‘ ÌÌ|–ffCombined“random“generator“using“2“(PMM)LGC“generatorsŽ¡¡‘0Reference:‘ ÌÌ|–ffPierre“L'Ecuyer“and“Serge“Cote,Ž¡‘0|–ff"Implementing“a“Random“Number“Package“with“SplittingŽ¡‘0|–ffFacilities."“ACM“Transactions“on“Mathematical“SoftwareŽ¡‘0|–ffvol.“17“no.“1,“March“1991,“pp.“98-111.Ž¡‘0|–ffTheir“name“for“the“generator:“'split.c'.Ž¡‘0|–ffSee“also“.Ž¡¡‘0Comments:‘ ÌÌ|–ffThis“portable“generator“is“based“on“a“backbone“generatorŽ¡‘0|–ffwhich“is“a“combination“of“2“(PMM)LCG“generators.“It“has“aŽ¡‘0|–ffperiod“length“of“almost“2^61“(2.3e18).Ž¡¡‘0|–ffThe“backbone“generator's“period“can“be“split“up“into“aŽ¡‘0|–ffnumber“of“'virtual“generators'“(A),“each“of“which“can“be“setŽ¡‘0|–ffto“access“a“number“of“'segments'“(V)“of“length“W,“subject“toŽ¡‘0|–ffthe“constraint“that“A“*“V“*“W“<=“2^60.Ž¡¡‘0|–ffThis“is“possible“because“the“backbone“generator“hasŽ¡‘0|–ff'jump-ahead“facilities'“--“i.e.“a“quick“method“of“calculatingŽ¡‘0|–ffthe“state“of“the“generator“at“a“given“point“in“its“cycleŽ¡‘0|–ffwithout“having“to“actually“draw“a“large“number“of“variates.Ž¡¡‘0Algorithm–ff|“state(j)“=“seed(j)Ž¡‘0for–ffeach“|“newstate(j)“=“(a(j)“*“oldstate(j))“mod“m(j)Ž¡‘0generator:‘ ÌÌ|–ffoutput(j)“=“state(j)Ž¡¡‘0Algorithm–ff|“output“=“(state(1)“-“state(2))“mod“m(0)Ž¡‘0for‘ffcombination:|Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ý > “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂComments:‘ ÌÌ|–ffFor“a“discussion“of“PMMLCG“generators,“see“the“source“fileŽ¤,†‘/ºâ|‘ffPMMLCGgen.h.Ž¡¡‘/ºâConfiguration–ff|“unsigned“int“numGenerators;“//“#“virtual“generatorsŽ¡‘/ºâparameters:‘ ÌÌ|–ffunsigned“int“numSegments;“//“log2(#segments/vGen)Ž¡‘/ºâ|–ffunsigned“int“segmentLength;“//“log2(segment“length)Ž¡¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“state“[numGenerators]“[2];Ž¡‘/ºâ|–ff(each“virtual“generator“has“a“4-integer“state“vector)Ž¡¡‘/ºâOutput–fftypes“|“unsigned“int“in“[0,unsignedMax].Ž¡‘/ºâ(for–ffeach“|“float“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâvirtual–ff|“double“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâgenerator):‘ ÌÌ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“The“combined“generator“yields“output“in“the“range“[0,m0-1]Ž¡‘/ºâ|–ff(i.e.“[0,2147483562].)Ž¡¡‘/ºâLimits–ffon“|“Number“of“generators“A“<=“2^25‘ ÌÌ(33,554,432)Ž¡‘/ºâparameters:‘ ÌÌ|–ff(You'll“likely“run“out“of“memory“before“then“...)Ž¡‘/ºâ|–ffNumber“of“segments“/“generator“<=“2^60“(i.e.“v“<=“60)Ž¡‘/ºâ|–ffLength“of“each“segment“<=“2^60“(i.e.“w“<=“60)Ž¡¡‘/ºâDefaults:‘ ÌÌ|–ffA=32,“v=20,“w=30Ž¡¡‘/ºâValid–ffseeds:‘ ÌÌ|“Using“create:setStateFromSeed:“in“[1,“2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:Ž¡‘/ºâ|–ffThe“generator“must“be“seeded“with“2“starting“seeds:Ž¡‘/ºâ|‘ ÌÌSeed[0]:–ff[1,“2147483562]“=“[1,m1-1]Ž¡‘/ºâ|‘ ÌÌSeed[1]:–ff[1,“2147483398]“=“[1,m2-1]Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“the“component“generatorsŽ¡‘/ºâ|–ffhave“a“single“full“cycle“of“length“(m-2).Ž¡‘/ºâ|–ffThe“combined“generator“has“a“cycle“length“ofŽ¡‘/ºâ|–ff(m1-1)*(m2-1)/2“=“2147483562*2147483398/2“~=“2^61.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡‘/ºâ|–ffThe“combined“generator“has“much“better“statisticalŽ¡‘/ºâ|–ffproperties“than“either“of“its“component“PMMLCG's.Ž¡¡‘/ºâReference–fffor“|“L'Ecuyer“and“Cote,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâImplementation‘ ÌÌ|–ffThe“code“for“-getUnsignedMax“uses“a“trick“devised“byŽ¡‘/ºâcomment:‘+30|–ffSchrage“to“avoid“32-bit“overflow“when“calculating“theŽ¡‘/ºâ|–ffnext“state“(i.e.“using“q=m/a“and“r=m%a“as“auxiliaryŽ¡‘/ºâ|–ffvalues).“Using“64-bit“math“(long“long“integers)“is“moreŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹þ c “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffstraightforward.“Unfortunately,“on“x86“at“least,“there“isŽ¤+‘/ºâ|–ffa“significant“speed“penalty“for“doing“so.Ž¡‘/ºâ|–ffThe“output,“however,“would“be“identical.“YMMV.Ž¡¡‘/ºâC2LCGXgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:’™7.029‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘5ÿü9.049“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“16.725“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“0.526“(time“1.900)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--Ž¡¡‘/ºâParameters:‘ ÌÌ|–ffa[COMPONENTS]“=“Çf– fdÂ40014,“40692‘ffÇgŽ¡‘/ºâÂ|–ffm[COMPONENTS]“=“Çf“Â2147483563,“2147483399“ÇgŽ¡¡‘/ºâÂReference–fffor“|“L'Ecuyer“and“Cote,“op.“cit.Ž¡‘/ºâparameters:‘ ÌÌ|Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“length“close“to“2^60“(2.3e18).Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“The“authors“performed“an“exhaustive“search“for“componentŽ¡‘/ºâ|–ffgenerators“that“would“yield“the“best“statistical“quality.Ž¡¡‘/ºâReference–fffor“|“L'Ecuyer“and“Cote,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|ŽŸ‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿ+¿(./ACGgen.html)ŽŸ8äïhtml:ï html:¦’áøRïï html:Ÿ+(./Interface.html)ŽŸÕSïhtml:ï html:¦’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿ+(./C2MRG3gen.html)ŽŸ‘0„¤ŽŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ÿ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ ‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:ŽŸ‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ #Ä “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½C2MRG3gen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffC2MRG3“--Ž¡‘0//‘32long–ffcomponent“based“generator“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype–ffC2MRG3gen““@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“C2MRG3Ž¡¡‘0Description:‘ ÌÌ|–ffCombination“of“2“Multiple“Recursive“LCG“GeneratorsŽ¡¡‘0Reference:‘ ÌÌ|–ffPierre“L'Ecuyer,Ž¡‘0|–ff"Combined“Multiple“Recursive“Random“Number“Generators."Ž¡‘0|–ffSee“.Ž¡¡‘0|–ffFor“a“discussion“of“MRG“generators,“see“MRGgen.h.Ž¡¡‘0Algorithm:‘ ÌÌ|–ffFor“each“generator:Ž¡‘0|–ffx_n“=“(a_1*x_n-1“+“a_2*x_n-2“...“+“a_k*x_n-k)“mod“mŽ¡‘0|–ffCombining“them:Ž¡‘0|–ffx“=“(x1“-“x2)“mod“m1Ž¡¡‘0Comments:‘ ÌÌ|–ffCombinations“of“like“generators“are“shown“to“have“betterŽ¡‘0|–ffstatistical“properties“than“single“generators.Ž¡¡‘0Implementation:‘ ÌÌ|–ffThe“components“of“this“generator“each“has“two“nonzeroŽ¡‘0|–ffmultipliers“(and“one“that's“zero).“They“use“differentŽ¡‘0|–ffmoduli“(2^31-1,“2145483479.)Ž¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“m[2]“//“modulusŽ¡‘0|–ffunsigned“int“a1[2],“ak[2]“//“multipliersŽ¡‘0|–ffunsigned“int“k[2]“//“the“order“of“the“generatorŽ¡¡‘0State:‘ ÌÌ|–ffunsigned“int“x[k][2]“//“state“vectorŽ¡¡‘0Output–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘0|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘0|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘0|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ %“ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ff(See“the“implementation“file“for“more“details.)Ž¤.Œ¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,unsignedMax]“=“[0,m1-2].Ž¡¡‘/ºâValid–ffseeds:‘ ÌÌ|“This“generator“requires“3“seeds“for“each“component:Ž¡‘/ºâ|–ffwithin“[1,m1-1]“for“component“1;Ž¡‘/ºâ|–ffwithin“[1,m2-1]“for“component“2.Ž¡‘/ºâ|–ffUsing“create:setStateFromSeed:“in“[1,2^32-1]Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“cycle“of“length“(m1^3-1)(m2^3-1)/2Ž¡‘/ºâ|–ffor“2^184“<“cycle“<“2^185“(4.9e55).Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“L'Ecuyer“et“al,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâC2MRG3gen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*13.459‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–15.203“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“29.699“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“0.275“(time“3.640)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--Ž¡¡‘/ºâParameters:‘ ÌÌ|–ffunsigned“int“k“=“3“//“lag“orderŽ¡¡‘/ºâ|–ffunsigned“int“m1“=“2^31“-“1“//“modulusŽ¡‘/ºâ|–ffunsigned“int“a12“=“63308“//“multiplierŽ¡‘/ºâ|–ffunsigned“int“a13“=“-183326“//“multiplierŽ¡¡‘/ºâ|–ffunsigned“int“m2“=“2145483479“//“modulusŽ¡‘/ºâ|–ffunsigned“int“a21“=“86098“//“multiplierŽ¡‘/ºâ|–ffunsigned“int“a23“=“-539608“//“multiplierŽ¡¡‘/ºâReference–fffor“|“L'Ecuyer“et“al,“op.“cit.,“Table“3.Ž¡‘/ºâparameters:‘ ÌÌ|Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“lengthŽ¡‘/ºâ|–ff((2^31-1)^3“-“1)“*“(2145483479^3“-“1)“/“2“~=“4.89e55,Ž¡‘/ºâ|–ffi.e.“2^184“<“cycle“<“2^185.Ž¡‘/ºâ|–ff(The“paper,“in“apparent“error,“claimsŽ¡‘/ºâ|–ffthat“the“cycle“is“close“to“2^205.)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ -; “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤‘/ºâÂOutput–ffQuality:‘ ÌÌ|“Good.“Parameters“chosen“on“the“basis“of“theoryŽ¡‘/ºâ|–ffand“empirical“testing.Ž¡¡‘/ºâReference–fffor“|“L'Ecuyer“et“al,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦¿(./C2LCGXgen.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(./C2TAUS1-3gen.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ 5f “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½C2T‘þ"LA‘þö”USgen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffC2TAUS1,“C2TAUS2,“C2TAUS3“--Ž¡‘0//‘32short–ffcomponent“based“generator“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype–ffC2TAUSgen‘™˜“@endŽ¡‘0@deftype–ffC2TAUS1gen‘32“@endŽ¡‘0@deftype–ffC2TAUS2gen‘32“@endŽ¡‘0@deftype–ffC2TAUS3gen‘32“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀGeneral‘QëDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“C2TAUSŽ¡¡‘0Description:‘ ÌÌ|–ffCombined“Tausworthe“GeneratorŽ¡‘0|–ffbased“on“2“component“generators“of“periods“2^31-1“and“2^29-1Ž¡¡‘0Reference:‘ ÌÌ|–ffShu“Tezuka“and“Pierre“L'Ecuyer,Ž¡‘0|–ff"Efficient“and“Portable“Combined“TauswortheŽ¡‘0|–ffRandom“Number“Generators."Ž¡‘0|–ffACM“Transactions“on“Modeling“and“Computer“Simulation,Ž¡‘0|–ffvol.“1“no.“2,“April“1991,“pp.“99-112.Ž¡¡‘0|–ffOriginal“reference“for“the“Tausworthe“algorithm:Ž¡‘0|–ffR.“C.“Tausworthe,“"Random“Numbers“Generated“by“LinearŽ¡‘0|–ffRecurrence“modulo“2",“Math.“Comput.“19“(1965),“201-209.Ž¡¡‘0Algorithm:‘ ÌÌ|–ffstate“=“seed,“then:Ž¡¡‘0(Each–ff|“b“=“((old“<<“Q)“^“old)“&“maskŽ¡‘0component:)‘ ÌÌ|–ffnew“=“((old“<<“S)“^“(b“>>“(P-S))“&“maskŽ¡¡‘0(Combination:)‘ ÌÌ|–ffoutput“=“((new1“^“(new2“<<“(P1-P2))Ž¡¡‘0Implementation:‘ ÌÌ|Ž¡¡‘0Parameters:‘ ÌÌ|–ffint‘32P“[2]“//“word“lengthŽ¡‘0|–ffint‘32Q“[2]“//Ž¡‘0|–ffint‘32S“[2]“//Ž¡‘0|–ffint“PmS“[2]“//“P“-“SŽ¡‘0|–ffint“P1mP2“//“P[0]“-“P[1]ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ : “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffunsigned“int“Mask[2]“//“2^P“-“1Ž¤.l¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“state[2]“//“state“vectorŽ¡¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,2^31-1]“may“be“returnedŽ¡‘/ºâ|–ff(i.e.“[0,2147483647].)Ž¡¡‘/ºâValid–ffseeds:‘ ÌÌ|“Using“create:setStateFromSeed:“in“[1,“2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:Ž¡‘/ºâ|‘ ÌÌSeed[0]–ffmust“be“in“[1,Mask[0]];Ž¡‘/ºâ|‘ ÌÌSeed[1]–ffmust“be“in“[1,Mask[1]];Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffThese“generators“have“a“single“full“cycleŽ¡‘/ºâ|–ffof“length“Mask1“*“Mask2“~=“2^60“(1.15e18).Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“The“authors“conducted“an“exhaustive“search“among“candidateŽ¡‘/ºâ|–ffTausworthe“generators“to“find“the“combination“that“had“theŽ¡‘/ºâ|–ffbest“lattice“structure.“(Single“Tausworthe“generators“do“notŽ¡‘/ºâ|–ffhave“acceptable“properties.)“The“3“generators“implementedŽ¡‘/ºâ|–ffhere“were“retained“as“the“best“found.Ž¡¡‘/ºâReference–fffor“|“Tezuka“and“L'Ecuyer,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâC2TAUSgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:’™4.078‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘5ÿü5.932“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“10.920“uSŽ¡¡‘/ºâRelative‘ffspeed:ŽŸ‘/ºâ|–ffSpeed“0.907“(time“1.103)“relative“to“MT19937“getUnsignedSampleŽºâŸ‡®ïhtml:ï html:ŸªÖÀC2T‘þqêA‘ÿ"ÐUS1gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª>‘0ÂParameters:‘ ÌÌ|–ffP“=“31“so“Mask“=“2^31-1Ž¡‘0(component–ff1)“|“S“=“12“so“PmS“=“19Ž¡‘0|–ffQ“=“13Ž¡¡‘0|–ffP“=“29“so“Mask“=“2^29-1Ž¡‘0(component–ff2)“|“S“=“17“so“PmS“=“12ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ Ac “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffQ“=‘ ÌÌ2Ž¤.I¡‘/ºâReference–fffor“|“These“values“recommended“by“Tezuka“and“L'Ecuyer,Ž¡‘/ºâparameters:‘ ÌÌ|–ffop.“cit.,“table“I“p.“107.Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“length“~“2^60.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Tezuka“and“L'Ecuyer,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Žºâ©‡®ïhtml:ï html:Ÿª³ÀC2T‘þqêA‘ÿ"ÐUS2gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª‘0ÂParameters:‘ ÌÌ|–ffP“=“31“so“Mask“=“2^31-1Ž¡‘0(component–ff1)“|“S“=“21“so“PmS“=“10Ž¡‘0|–ffQ“=‘ ÌÌ3Ž¡¡‘0|–ffP“=“29“so“Mask“=“2^29-1Ž¡‘0(component–ff2)“|“S“=“17“so“PmS“=“12Ž¡‘0|–ffQ“=‘ ÌÌ2Ž¡¡‘0Reference–fffor“|“These“values“recommended“by“Tezuka“and“L'Ecuyer,Ž¡‘0parameters:‘ ÌÌ|–ffop.“cit.,“table“II“p.“107.Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“~“2^60.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘0Reference–fffor“|“Tezuka“and“L'Ecuyer,“op.cit.Ž¡‘0output‘ffquality:‘ ÌÌ|Ž¦ïhtml:ï html:Ÿª³ÀC2T‘þqêA‘ÿ"ÐUS3gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª‘0ÂParameters:‘ ÌÌ|–ffP“=“31“so“Mask“=“2^31-1Ž¡‘0(component–ff1)“|“S“=“13“so“PmS“=“18Ž¡‘0|–ffQ“=“13Ž¡¡‘0|–ffP“=“29“so“Mask“=“2^29-1Ž¡‘0(component–ff2)“|“S“=“20“so“PmS“=‘ ÌÌ9Ž¡‘0|–ffQ“=‘ ÌÌ2Ž¡¡‘0Reference–fffor“|“These“values“recommended“by“Tezuka“and“L'Ecuyer,ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ J “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂparameters:‘ ÌÌ|–ffop.“cit.,“table“III“p.“107.Ž¤¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“length“~“2^60.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Tezuka“and“L'Ecuyer,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦¿(./C2MRG3gen.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(./C3MWCgen.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ Pª “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½C3MWCgen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffC3MWC“--Ž¡‘0//‘32long–ffcomponent“based“generator“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype–ffC3MWCgen‘32“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“C3MWCŽ¡¡‘0Description:‘ ÌÌ|–ffCombined“Multiply-With-Carry“generatorŽ¡¡‘0Reference:‘ ÌÌ|–ffArticle“posted“to“Usenet“in“1994“by“George“Marsaglia,Ž¡‘0|–ff"The“Mother“of“all“Random“Number“Generators."Ž¡‘0|–ffSource“found“at“Ž¡‘0|–ffAlso“document“/papers/mwc1.ps“on“his“Diehard“CD-ROM,Ž¡‘0|–fffound“at“.Ž¡¡‘0Algorithm:‘ ÌÌ|–ffK“=“a“*“(K“&“65535)“+“(K>>16);Ž¡‘0|–ffJ“=“b“*“(J“&“65535)“+“(J>>16);Ž¡‘0|–ffI“=“c“*“(I“&“65535)“+“(I>>16);Ž¡‘0|–ffL“=“d“*“(L“&“65535)“+“(L>>16);Ž¡‘0|–ffM“=“e“*“(M“&“65535)“+“(M>>16);Ž¡‘0|–ffN“=“f“*“(N“&“65535)“+“(N>>16);Ž¡‘0|–ffreturn“((K+I+M)>>16)“+“(J+L+N);Ž¡¡‘0Comments:‘ ÌÌ|–ffThis“generator“is“a“combination“of“3“MWC“generators,Ž¡‘0|–ffeach“of“which“is“a“combination“of“2“16-bitŽ¡‘0|–ffMultiply-With-Carry“generators.Ž¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“a“=“30903“//“multiplierŽ¡‘0|–ffunsigned“int“b“=“18000Ž¡‘0|–ffunsigned“int“c“=“29013Ž¡‘0|–ffunsigned“int“d“=“30345Ž¡‘0|–ffunsigned“int“e“=“30903Ž¡‘0|–ffunsigned“int“f“=“31083Ž¡¡‘0State:‘ ÌÌ|–ffunsigned“int“K,J,I,L,M,N“//“state“vectorŽ¡¡‘0Output–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ Uµ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¤—‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,unsignedMax]“=“[0,2^32-1].Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,“2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“each“component“may“haveŽ¡‘/ºâ|–ffa“'state'“<=“0xffff“and“a“carry“<=“(multiplier-1),“so“thatŽ¡‘/ºâ|–fffor“the“first“component“the“largest“seed“allowed“isŽ¡‘/ºâ|–ff(a-1)<<16“+“65535.Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffThis“generator“is“claimed“to“be“strictly“periodic,“with“aŽ¡‘/ºâ|–ffperiod“>“2^118.“There“may“be“more“than“one“cycle.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Marsaglia,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâC3MWCgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:’™6.437‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘5ÿü8.200“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“15.562“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“0.574“(time“1.741)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--ŽŸ‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿ—¿(./C2TAUS1-3gen.html)ŽŸ8äïhtml:ï html:¦’áøRïï html:Ÿ—(./Interface.html)ŽŸÕSïhtml:ï html:¦’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿ—(./C4LCGXgen.html)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ] “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ eX “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½C4LCGXgen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffC4LCGXgen“--Ž¡‘0//‘32short–ffcomponent“based“generator“with“splitting“facilities.“Recommended.Ž¡‘0//Ž¡‘0@deftype–ffC4LCGXgen‘ ÌÌ“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“C4LCGXŽ¡¡‘0Description:‘ ÌÌ|–ffCombined“random“generator“using“4“(PMM)LGC“generatorsŽ¡¡‘0Reference:‘ ÌÌ|–ffPierre“L'Ecuyer“and“Terry“H.“Andres,Ž¡‘0|–ff"A“Random“Number“Generator“Based“on“the“CombinationŽ¡‘0|‘ ÌÌof–ffFour“LCGs",“17“December“1996.Ž¡‘0|–ffTo“appear“in“Mathematics“and“Computers“in“Simulation.“See:Ž¡‘0|‘ff.Ž¡‘0|–ffTheir“name“for“the“generator:“'clcg4'.Ž¡¡‘0Comments:‘ ÌÌ|–ffThis“portable“generator“is“based“on“a“backbone“generatorŽ¡‘0|–ffwhich“is“a“combination“of“4“(PMM)LCG“generators.“It“has“aŽ¡‘0|–ffperiod“length“of“(m1-1)(m2-1)(m3-1)(m4-1)“/“8,“or“almostŽ¡‘0|–ff2^121“(2.6e36).Ž¡¡‘0|–ffThe“backbone“generator's“period“can“be“split“up“into“aŽ¡‘0|–ffnumber“of“'virtual“generators'“(A),“each“of“which“can“be“setŽ¡‘0|–ffto“access“a“number“of“'segments'“(V)“of“length“W,“subject“toŽ¡‘0|–ffthe“constraint“that“A“*“V“*“W“<=“2^120.Ž¡¡‘0|–ffThis“is“possible“because“the“backbone“generator“hasŽ¡‘0|–ff'jump-ahead“facilities'“--“i.e.“a“quick“method“of“calculatingŽ¡‘0|–ffthe“state“of“the“generator“at“a“given“point“in“its“cycleŽ¡‘0|–ffwithout“having“to“actually“draw“a“large“number“of“variates.Ž¡¡‘0Algorithm–ff|“state(j)“=“seed(j)Ž¡‘0for–ffeach“|“newstate(j)“=“(a(j)“*“oldstate(j))“mod“m(j)Ž¡‘0generator:‘ ÌÌ|–ffoutput(j)“=“state(j)Ž¡¡‘0Algorithm–ff|“output“=“(state(1)“-“state(2)“+“state(3)“-“state(4))“mod“m(0)Ž¡‘0for‘ffcombination:|ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ g9 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤,†‘/ºâÂComments:‘ ÌÌ|–ffFor“a“discussion“of“PMMLCG“generators,“see“the“source“fileŽ¡‘/ºâ|‘ffPMMLCGgen.h.Ž¡¡‘/ºâConfiguration–ff|“unsigned“int“numGenerators;“//“#“virtual“generatorsŽ¡‘/ºâparameters:‘ ÌÌ|–ffunsigned“int“numSegments;“//“log2(#segments/vGen)Ž¡‘/ºâ|–ffunsigned“int“segmentLength;“//“log2(segment“length)Ž¡¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“state“[numGenerators]“[4];Ž¡‘/ºâ|–ff(each“virtual“generator“has“a“4-integer“state“vector)Ž¡¡‘/ºâOutput–fftypes“|“unsigned“int“in“[0,unsignedMax].Ž¡‘/ºâ(for–ffeach“|“float“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâvirtual–ff|“double“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâgenerator):‘ ÌÌ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“The“combined“generator“yields“output“in“the“range“[0,m0-2]Ž¡‘/ºâ|–ff(i.e.“[0,2147483645].)Ž¡¡‘/ºâLimits–ffon“|“Number“of“generators“A“<=“2^25‘ ÌÌ(33,554,432)Ž¡‘/ºâparameters:‘ ÌÌ|–ff(You'll“likely“run“out“of“memory“before“then“...)Ž¡‘/ºâ|–ffNumber“of“segments“/“generator“<=“2^63“(i.e.“v<=63)Ž¡‘/ºâ|–ffLength“of“each“segment“<=“2^63“(i.e.“w<=63)Ž¡¡‘/ºâDefaults:‘ ÌÌ|–ffA=128,“v=31,“w=41Ž¡¡‘/ºâValid–ffseeds:‘ ÌÌ|“Using“create:setStateFromSeed:“in“[1,“2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:Ž¡‘/ºâ|–ffThe“generator“must“be“seeded“with“4“starting“seeds:Ž¡‘/ºâ|‘ ÌÌSeed[0]:–ff[1,“2147483646]“=“[1,m1-1]Ž¡‘/ºâ|‘ ÌÌSeed[1]:–ff[1,“2147483542]“=“[1,m2-1]Ž¡‘/ºâ|‘ ÌÌSeed[2]:–ff[1,“2147483422]“=“[1,m3-1]Ž¡‘/ºâ|‘ ÌÌSeed[3]:–ff[1,“2147483322]“=“[1,m4-1]Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“the“component“generatorsŽ¡‘/ºâ|–ffhave“a“single“full“cycle“of“length“(m-1).Ž¡‘/ºâ|–ffThe“combined“generator“has“a“cycle“length“ofŽ¡‘/ºâ|–ff2147483646*2147483542*2147483422*2147483322/8“>“2^120.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡‘/ºâ|–ffThe“combined“generator“has“much“better“statisticalŽ¡‘/ºâ|–ffproperties“than“either“of“its“component“PMMLCG's.Ž¡¡‘/ºâReference–fffor“|“L'Ecuyer“and“Andres,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâImplementation‘ ÌÌ|–ffThe“code“for“-getUnsignedMax“uses“a“trick“devised“byŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ o´ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂcomment:‘+30|–ffSchrage“to“avoid“32-bit“overflow“when“calculating“theŽ¤Æ™‘/ºâ|–ffnext“state“(i.e.“using“q=m/a“and“r=m%a“as“auxiliaryŽ¡‘/ºâ|–ffvalues).“Using“64-bit“math“(long“long“integers)“is“moreŽ¡‘/ºâ|–ffstraightforward.“Unfortunately,“on“x86“at“least,“there“isŽ¡‘/ºâ|–ffa“significant“speed“penalty“for“doing“so.Ž¡‘/ºâ|–ffThe“output,“however,“would“be“identical.“YMMV.Ž¡¡‘/ºâC4LCGXgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*11.688‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–13.644“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“26.154“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“0.316“(time“3.160)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff|“-----------------------------------------------------------Ž¦‘/ºâ---Ž¡¡‘/ºâParameters:‘ ÌÌ|–ffa[COMPONENTS]“=“Çf‘ fdÂ45991,‘ÿþ207707,Ž¡‘/ºâ|– fd138556,“49689‘ffÇgŽ¡‘/ºâÂ|–ffm[COMPONENTS]“=“Çf“Â2147483647,“2147483543,Ž¡‘/ºâ|‘ ÌÌ2147483423,–ff2147483323“ÇgŽ¡¡‘/ºâÂReference–fffor“|“L'Ecuyer“and“Andres,“op.“cit.Ž¡‘/ºâparameters:‘ ÌÌ|Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“length“close“to“2^121“(2.6e36).Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“The“authors“performed“an“exhaustive“search“for“componentŽ¡‘/ºâ|–ffgenerators“that“would“yield“the“best“statistical“quality.Ž¡¡‘/ºâReference–fffor“|“L'Ecuyer“and“Andres,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|ŽŸ‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:ŸÆ™¿(./C3MWCgen.html)ŽŸ8äïhtml:ï html:¦’áøRïï html:ŸÆ™(./Interface.html)ŽŸÕSïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ xù “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÖ\’á³4ï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽºâ© ïhtml:ï html:¤¿(./LCG1-3gen.html)Ž¡‘0„¤ŽŽ¦ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ 3 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½LCG1-3gen‘/ClassesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤0÷‘0Â//Ž¡‘0//–ffLCG1,“LCG2,“LCG3“--Ž¡‘0//‘32single–ffshort“random“number“generators,Ž¡‘0//‘32NOT–ffrecommended“for“serious“use;“these“are“included“forŽ¡‘0//‘32historical–ffreasons“(compatibility“with“earlier“releases).Ž¡‘0//Ž¡‘0@deftype–ffLCGgen‘ fd“@endŽ¡‘0@deftype–ffLCG1gen‘+30“@endŽ¡‘0@deftype–ffLCG2gen‘+30“@endŽ¡‘0@deftype–ffLCG3gen‘+30“@endŽŸ‘0„¤ŽŽ¤G®ïhtml:ï html:©íaÀUse–Qëof“these“generators“is“ïhtml:ï html:NO‘ÿOT“RecommendedŽŸ^5‘0„¤ŽŽ¡ïhtml:ï html:¦General‘QëDocumentationŽŸ ¢Âïhtml:ï html:Ÿìj‘0ÂGenerator–ffname:‘ ÌÌ|“LCGŽ¤0÷¡‘0Description:‘ ÌÌ|–ffLinear“Congruential“GeneratorŽ¡¡‘0Reference:‘ ÌÌ|–ffThis“is“a“classic“generator.Ž¡‘0|–ffSee“for“example“Donald“Knuth,Ž¡‘0|–ffThe“Art“of“Computer“Programming,Ž¡‘0|–ffvol.“II,“"Seminumerical“Algorithms."Ž¡¡‘0|–ffstate“=“seedŽ¡‘0Algorithm:‘ ÌÌ|–ffnewstate“=“((a“*“oldstate)“+“c“)“mod“2^32Ž¡‘0|–ffoutput“=“stateŽ¡¡‘0Comments:‘ ÌÌ|–ffThis“generator“relies“on“controlled“overflow“at“32“bits.Ž¡‘0|–ffThis“requires“that“unsigned“be“a“32bit“value“that“followsŽ¡‘0|–ffANSI“C“rules.Ž¡‘0|–ffKnuth“claims“that“the“adder“c“does“not“matter“much,“asŽ¡‘0|–fflong“as“it“has“no“factors“in“common“with“the“modulus“2^32.Ž¡¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“c“//“adderŽ¡‘0|–ffunsigned“int“a“//“multiplierŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ƒ— “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤.l‘/ºâÂState:‘ ÌÌ|–ffunsigned“int“state“//“a“"state“vector"“of“length“1Ž¡¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,2^32-1]“may“be“returnedŽ¡‘/ºâ|–ff(i.e.“[0,4294967295].)Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“[1,2^32-1]Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“these“generatorsŽ¡‘/ºâ|–ffhave“a“single“full“cycle“of“length“(2^32).Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Low“order“bits“are“poor.Ž¡¡‘/ºâReference–fffor“|“Knuth,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâLCGgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*2.564‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–4.295“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“7.734“uSŽ¡¡‘/ºâRelative‘ffspeed:ŽŸ‘/ºâ|–ffSpeed“1.442“(time“0.693)“relative“to“MT19937“getUnsignedSampleŽºâŸ‡®ïhtml:ï html:ŸªÖÀLCG1gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª>‘0ÂParameters:‘ ÌÌ|–ffa“=‘ÿþ1,664,525Ž¡‘0|–ffc“=“1,013,904,223Ž¡¡‘0Reference–fffor“|“The“multiplier“is“from“Knuth“vol“II“(line“26“of“table).Ž¡‘0parameters:‘ ÌÌ|–ffAdder“is“from“Numerical“Recipes,“in“turn“from“H.W.LewisŽ¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“m.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Low-order“bits“are“poor.Ž¡¡‘0Reference–fffor“|“Knuth,“op.cit.“and“Numerical“Recipes.Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ŠÔ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸçåÀLCG2gen‘QëDocumentationŽ© âcïhtml:ï html:Ÿ|Ã‘0ÂParameters:‘ ÌÌ|–ffa“=‘+3069,069Ž¤ñ‘0|–ffc“=“1,013,904,223Ž¡¡‘0Reference–fffor“|“The“multiplier“is“from“Knuth“vol“II“(line“25“of“table).Ž¡‘0parameters:‘ ÌÌ|–ffAdder“is“from“Numerical“Recipes,“in“turn“from“H.W.LewisŽ¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“m.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Low-order“bits“are“poor.Ž¡¡‘0Reference–fffor“|“Knuth,“op.cit.“and“Numerical“Recipes.Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŸ‡®ïhtml:ï html:Ÿ}[ÀLCG3gen‘QëDocumentationŽ¦ïhtml:ï html:Ÿ|Ã‘0ÂParameters:‘ ÌÌ|–ffa“=‘321,664,525Ž¡‘0|–ffc“=“152,193,325Ž¡¡‘0Reference–fffor“|“The“multiplier“is“from“Knuth“vol“II“(line“26“of“table).Ž¡‘0parameters:‘ ÌÌ|–ffAdder“is“from“Numerical“Recipes,“in“turn“from“H.W.LewisŽ¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“m.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Low-order“bits“are“poor.Ž¡¡‘0Reference–fffor“|“Knuth,“op.cit.“and“Numerical“Recipes.Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŸ‘0„¤ŽŽ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿñ¿(./C4LCGXgen.html)ŽŸ8äïhtml:ï html:¦’áøRïï html:Ÿñ(./Interface.html)ŽŸÕSïhtml:ï html:¦’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ’ý “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿(./MRG5-7gen.html)ŽŸ‘/ºâ„¤ŽŽºâŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ šj “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½MRG5-7gen‘/ClassesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffMRG5,“MRG6,“MRG7“--Ž¡‘0//‘32single–fflong“generators“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype‘ffMRGgen‘ fd‘ ÌÌ@endŽ¡‘0@deftype–ffMRG5gen‘ fd“@endŽ¡‘0@deftype–ffMRG6gen‘ fd“@endŽ¡‘0@deftype–ffMRG7gen‘ fd“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀGeneral‘QëDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“MRGŽ¡¡‘0Description:‘ ÌÌ|–ffMultiple“Recursive“LCG“GeneratorŽ¡¡‘0Reference:‘ ÌÌ|–ffPierre“L'Ecuyer,“Francois“Blouin“and“Raymond“Couture,Ž¡‘0|–ff"A“Search“for“Good“Multiple“Recursive“Random“Generators."Ž¡‘0|–ffSee“.Ž¡¡‘0Algorithm:‘ ÌÌ|–ffx_n“=“(a_1*x_n-1“+“a_2*x_n-2“...“+“a_k*x_n-k)“mod“mŽ¡¡‘0Comments:‘ ÌÌ|–ffThese“generators“require“k“multipliers“and“k“past“valuesŽ¡‘0|–ffto“be“kept.“In“their“paper,“the“authors“investigate“MRG'sŽ¡‘0|–ffof“order“k“from“1“to“7.“They“provide“several“sets“ofŽ¡‘0|–ffparameters“which“they“recommend“out“of“a“large“number“thatŽ¡‘0|–ffwere“tested.“Generally,“the“quality“of“the“generatorsŽ¡‘0|–ffincreases“with“k.Ž¡¡‘0Implementation:‘ ÌÌ|–ffThe“authors“discovered“that“most“of“the“benefit“of“theseŽ¡‘0|–ffgenerators“can“be“had“if“only“a_1“and“a_k“are“nonzero“and“theŽ¡‘0|–ffrest“zero;“this“yields“faster“execution“since“only“2“termsŽ¡‘0|–ffneed“be“calculated.“We“implement“4“such“generators“here,Ž¡‘0|–ffall“with“modulus“m“close“to“2^31.Ž¡¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“m“//“modulusŽ¡‘0|–ffunsigned“int“a1,“ak“//“multipliersŽ¡‘0|–ffunsigned“int“k“//“the“order“of“the“generatorŽ¡¡‘0State:‘ ÌÌ|–ffunsigned“int“x[k]“//“state“vectorŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ œg “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤0Ã‘/ºâÂOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,unsignedMax]“=“[0,m-2].Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,“2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“[1,“unsignedMax]Ž¡‘/ºâ|–ff(unsignedMax“differs“between“MRG5,“MRG6,“MRG7)Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“these“generatorsŽ¡‘/ºâ|–ffhave“a“single“cycle“of“length“m^k“-“1.Ž¡‘/ºâ|–ffThus,“for“m“~=“2^31“we“have:Ž¡‘/ºâ|–ffk=5“=>“cycle“~=“2^155,Ž¡‘/ºâ|–ffk=6“=>“cycle“~=“2^186,Ž¡‘/ºâ|–ffk=7“=>“cycle“~=“2^217.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“L'Ecuyer“et“al,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâMRG5gen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:’™9.674‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–11.524“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“22.135“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“0.382“(time“2.616)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--Ž¡¡‘/ºâMRG6gen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*10.449‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–12.337“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“27.735“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž¦‘/ºâ|–ffSpeed“0.354“(time“2.826)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--Ž¡¡‘/ºâMRG7gen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*10.913‘ffuSŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ¤Ž “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–12.764“uSŽ¤/y‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“24.627“uSŽ¡¡‘/ºâRelative‘ffspeed:ŽŸ‘/ºâ|–ffSpeed“0.339“(time“2.951)“relative“to“MT19937“getUnsignedSampleŽºâ©‡®ïhtml:ï html:Ÿ«ãÀMRG5gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿ«K‘0ÂParameters:‘ ÌÌ|–ffunsigned“int“k“=“5“//“lag“orderŽ¡‘0|–ffunsigned“int“m“=“2^31“-“1“//“modulusŽ¡‘0|–ffunsigned“int“a1“=“107374182“//“multiplierŽ¡‘0|–ffunsigned“int“a5“=“104480“//“multiplierŽ¡¡‘0Reference–fffor“|“L'Ecuyer“et“al,“op.“cit.,“Table“3.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(2^31-1)^5“-“1,Ž¡‘0|–ffi.e.“2^154“<“cycle“<“2^155.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Good.“Parameters“chosen“on“the“basis“of“theoryŽ¡‘0|–ffand“empirical“testing.Ž¡¡‘0Reference–fffor“|“L'Ecuyer“et“al,“op.“cit.Ž¡‘0output‘ffquality:‘ ÌÌ|Ž¦ïhtml:ï html:Ÿ«ãÀMRG6gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿ«K‘0ÂParameters:‘ ÌÌ|–ffunsigned“int“k“=“6“//“lag“orderŽ¡‘0|–ffunsigned“int“m“=“2^31“-“1“//“modulusŽ¡‘0|–ffunsigned“int“a1“=“177786“//“multiplierŽ¡‘0|–ffunsigned“int“a6“=“64654“//“multiplierŽ¡¡‘0Reference–fffor“|“L'Ecuyer“et“al,“op.“cit.,“Table“3.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(2^31-1)^6“-“1,Ž¡‘0|–ffi.e.“2^185“<“cycle“<“2^186.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Good.“Parameters“chosen“on“the“basis“of“theoryŽ¡‘0|–ffand“empirical“testing.Ž¡¡‘0Reference–fffor“|“L'Ecuyer“et“al,“op.“cit.Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ m “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸçåÀMRG7gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿ{Ò‘0ÂParameters:‘ ÌÌ|–ffunsigned“int“k“=“7“//“lag“orderŽ¤‘0|–ffunsigned“int“m“=“2^31“-“19“//“modulusŽ¡‘0|–ffunsigned“int“a1“=“1071064“//“multiplierŽ¡‘0|–ffunsigned“int“a7“=“2113664“//“multiplierŽ¡¡‘0Reference–fffor“|“L'Ecuyer“et“al,“op.“cit.,“Table“3.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(2^31-1)^7“-“1,Ž¡‘0|–ffi.e.“2^216“<“cycle“<“2^217.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Good.“Parameters“chosen“on“the“basis“of“theoryŽ¡‘0|–ffand“empirical“testing.Ž¡¡‘0Reference–fffor“|“L'Ecuyer“et“al,“op.“cit.Ž¡‘0output‘ffquality:‘ ÌÌ|Ž©‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦¿(./LCG1-3gen.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(./MT19937gen.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ µ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½MT19937gen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffMT19937“--Ž¡‘0//‘32single–ff*very*“long“generator“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype–ffMT19937gen‘ ÌÌ“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“MT19937Ž¡¡‘0Description:‘ ÌÌ|–ffTwisted“GFSR“generatorŽ¡¡‘0Reference:‘ ÌÌ|–ffMakoto“Matsumoto“and“???“Nishimura,Ž¡‘0|–ffcode“posted“to“the“pLab“web“site,“xx/xx/97.Ž¡‘0|–ffSite:“Ž¡‘0|–ffCode:“Ž¡‘0|–ffArticle“reportedly“submitted“to“ACM“TOMACS.Ž¡¡‘0|Ž¡‘0Algorithm:‘ ÌÌ|Ž¡‘0|Ž¡¡‘0Comments:‘ ÌÌ|Ž¡¡‘0Implementation:‘ ÌÌ|Ž¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“N“//“size“of“state“arrayŽ¡‘0|–ffunsigned“int“M“//“lagŽ¡‘0|–ffunsigned“int“a“//“"Magic“numbers"Ž¡‘0|–ffunsigned“int“b,c“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“u,s,t,l“//‘™˜"‘ÿþ"Ž¡¡‘0State:‘ ÌÌ|–ffunsigned“int“state[N]“//“state“vectorŽ¡¡‘0Output–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘0|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘0|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘0|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘0|–ff(See“the“implementation“file“for“more“details.)Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ »Þ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,2^32]“may“be“returnedŽ¤.Œ¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜in“[1,2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“in“[1,2^32-1].Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffThis“generator“has“a“single“cycle“of“length“2^19937-1.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Excellent“equidistribution“properties“in“all“dimensionsŽ¡‘/ºâ|–ffup“to“623“are“claimed.Ž¡¡‘/ºâReference–fffor“|“Matsumoto“and“Nishimura,“op.“cit.Ž¡‘/ºâoutput–ffquality:‘ ÌÌ|“See“also“pLab“Report“#07“on“the“pLab“web“site.Ž¡¡‘/ºâMT19937gen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:’™3.698‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘5ÿü5.502“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“10.159“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“1.0“(time“1.0)“relative“to“itself“(it's“the“benchmark)Ž¡¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--Ž¡¡‘/ºâParameters:‘ ÌÌ|–ffunsigned“int“w=32“//“word“lengthŽ¡‘/ºâ|–ffunsigned“int“N=624“//“size“of“state“arrayŽ¡‘/ºâ|–ffunsigned“int“M=397“//“lagŽ¡‘/ºâ|–ffunsigned“int“s=7“//“'magic“vector'Ž¡‘/ºâ|–ffunsigned“int“t=15“//‘™˜"‘ÿþ"Ž¡‘/ºâ|–ffunsigned“int“u=11“//‘™˜"‘ÿþ"Ž¡‘/ºâ|–ffunsigned“int“l=18“//‘™˜"‘ÿþ"Ž¡‘/ºâ|–ffunsigned“int“b=0x102d1200“//‘™˜"‘ÿþ"Ž¡‘/ºâ|–ffunsigned“int“c=0x66e50000“//‘™˜"‘ÿþ"Ž¡‘/ºâ|–ffunsigned“int“a=0x6b5eccf6“//‘™˜"‘ÿþ"Ž¡¡‘/ºâReference–fffor“|“Matsumoto“and“Nishimura,“op.“cit.Ž¡‘/ºâparameters:‘ ÌÌ|Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“length“2^19937“-1,Ž¡‘/ºâ|–ffor“10^6001“!!!“(The“longest“period“yet.)Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.“Parameters“chosen“on“the“basis“of“theoryŽ¡‘/ºâ|–ffand“empirical“testing.Ž¡¡‘/ºâReference–fffor“|“Matsumoto“and“Nishimura,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ Â “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿ¿(./MRG5-7gen.html)ŽŸ8äïhtml:ï html:¦’áøRïï html:Ÿ(./Interface.html)ŽŸÕSïhtml:ï html:¦’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¤(./MWCA-Bgen.html)Ž¡‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ Êò “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½MWCA-Bgen‘/ClassesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffMWC“--Ž¡‘0//‘32two–fflong“generators“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype–ffMWCAgen‘™˜“@endŽ¡‘0@deftype–ffMWCBgen‘™˜“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀMWCAgen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª8‘0ÂGenerator–ffname:‘ ÌÌ|“MWCAŽ¡¡‘0Description:‘ ÌÌ|–ffMultiply-With-Carry“generatorŽ¡¡‘0Reference:‘ ÌÌ|–ffArticle“posted“to“Usenet“in“1994“by“George“Marsaglia,Ž¡‘0|–ff"The“Mother“of“all“Random“Number“Generators."Ž¡‘0|–ffSource“found“at“Ž¡‘0|–ffAlso“document“/papers/mwc1.ps“on“his“Diehard“CD-ROM,Ž¡‘0|–fffound“at“.Ž¡¡‘0Algorithm:‘ ÌÌ|–ffK“=“a“*“(K“&“65535)“+“(K>>16);Ž¡‘0|–ffJ“=“b“*“(J“&“65535)“+“(J>>16);Ž¡‘0|–ffreturn“(K<<16)“+“J;Ž¡¡‘0Comments:‘ ÌÌ|–ffThis“generator“is“a“combination“of“2“16-bitŽ¡‘0|–ffMultiply-With-Carry“generators.Ž¡¡‘0Implementation:‘ ÌÌ|Ž¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“a“=“30903“//“multiplierŽ¡‘0|–ffunsigned“int“b“=“18000“//“multiplierŽ¡¡‘0State:‘ ÌÌ|–ffunsigned“int“K,J“//“state“vectorŽ¡¡‘0Output–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘0|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘0|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘0|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘0|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘0Output–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,unsignedMax]“=“[0,2^32-1].ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ÎÖ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤/Ž‘/ºâÂValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,“2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“each“component“may“haveŽ¡‘/ºâ|–ffa“'state'“<=“65535“and“a“'carry'“<=“(multiplier-1).“ThusŽ¡‘/ºâ|–ffthe“first“component“has“a“maximum“seed“ofŽ¡‘/ºâ|–ff(“(a-1)“<<“16)“+“65535.Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffThis“generator“is“claimed“to“be“strictly“periodic,“with“aŽ¡‘/ºâ|–ffperiod“>“2^59.“(There's“possibly“two“such“cycles.)Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Marsaglia,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâMWCgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*3.399‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–5.131“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“9.447“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“1.088“(time“0.919)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--ŽºâŸG®ïhtml:ï html:ŸëøÀMWCBgen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿ«`‘0ÂGenerator–ffname:‘ ÌÌ|“MWCBŽ¡¡‘0Description:‘ ÌÌ|–ffMultiply-With-Carry“generatorŽ¡¡‘0Reference:‘ ÌÌ|–ffArticle“posted“to“Usenet“in“1994“by“George“Marsaglia,Ž¡‘0|–ff"The“Mother“of“all“Random“Number“Generators."Ž¡‘0|–ffSource“found“at“Ž¡‘0|–ffAlso“document“/papers/mwc1.ps“on“his“Diehard“CD-ROM,Ž¡‘0|–fffound“at“.Ž¡¡‘0Algorithm:‘ ÌÌ|–ffK“=“a“*“(K“&“65535)“+“(K>>16);Ž¡‘0|–ffJ“=“b“*“(J“&“65535)“+“(J>>16);Ž¡‘0|–ffreturn“(K<<16)“+“(J&65535);Ž¡¡‘0Comments:‘ ÌÌ|–ffThis“generator“is“a“combination“of“2“16-bitŽ¡‘0|–ffMultiply-With-Carry“generators.Ž¡¡‘0Implementation:‘ ÌÌ|–ffThis“generator“implements“an“alternate“manner“ofŽ¡‘0|–ffconjoining“the“two“components“(differs“from“MWCA).ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ Ö “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffIt“also“passes“all“tests“and“is“fast.Ž¤UE¡‘/ºâParameters:‘ ÌÌ|–ffunsigned“int“a“=“30903“//“multiplierŽ¡‘/ºâ|–ffunsigned“int“b“=“18000“//“multiplierŽ¡¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“K,J“//“state“vectorŽ¡¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,unsignedMax]“=“[0,2^32-1].Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,“2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“each“component“may“haveŽ¡‘/ºâ|–ffa“'state'“<=“65535“and“a“'carry'“<=“(multiplier-1).“ThusŽ¡‘/ºâ|–ffthe“first“component“has“a“maximum“seed“ofŽ¡‘/ºâ|–ff(“(a-1)“<<“16)“+“65535.Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffThis“generator“is“claimed“to“be“strictly“periodic,“with“aŽ¡‘/ºâ|–ffperiod“>“2^59.“(There's“possibly“two“such“cycles.)Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Marsaglia,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâMWCgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*3.399‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–5.131“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“9.447“uSŽ¡¡‘/ºâRelative‘ffspeed:ŽŸ‘/ºâ|–ffSpeed“1.088“(time“0.919)“relative“to“MT19937“getUnsignedSampleŽŸ‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:ŸUE¿(./MT19937gen.html)ŽŸ8äïhtml:ï html:¦’áøRïï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ÞÝ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐºâ¿(./Interface.html)ŽºâŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ© ïhtml:ï html:¤(./PMMLCG1-9gen.html)Ž¡‘0„¤ŽŽ¦ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ç “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½PMMLCG–/1-9“ClassesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffPMMLCG1,“PMMLCG2,“PMMLCG3“--Ž¡‘0//‘32single–ffshort“random“number“generators“recommended“for“use.Ž¡‘0//Ž¡‘0//–ffPMMLCG4,“PMMLCG5,“PMMLCG6,“PMMLCG7“--Ž¡‘0//‘32component–ffgenerators“of“C4LCGXŽ¡‘0//Ž¡‘0//–ffPMMLCG8,“PMMLCG9“--Ž¡‘0//‘32component–ffgenerators“of“C2LCGXŽ¡‘0//Ž¡‘0@deftype–ffPMMLCGgen‘32“@endŽ¡‘0@deftype–ffPMMLCG1gen‘ ÌÌ“@endŽ¡‘0@deftype–ffPMMLCG2gen‘ ÌÌ“@endŽ¡‘0@deftype–ffPMMLCG3gen‘ ÌÌ“@endŽ¡‘0@deftype–ffPMMLCG4gen‘ ÌÌ“@endŽ¡‘0@deftype–ffPMMLCG5gen‘ ÌÌ“@endŽ¡‘0@deftype–ffPMMLCG6gen‘ ÌÌ“@endŽ¡‘0@deftype–ffPMMLCG7gen‘ ÌÌ“@endŽ¡‘0@deftype–ffPMMLCG8gen‘ ÌÌ“@endŽ¡‘0@deftype–ffPMMLCG9gen‘ ÌÌ“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀGeneral‘QëDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“PMMLCGŽ¡¡‘0Description:‘ ÌÌ|–ffPrime“Modulus“Multiplicative“Linear“Congruential“GeneratorŽ¡¡‘0Reference:‘ ÌÌ|–ffStephen“K.“Park“and“Keith“W.“MillerŽ¡‘0|–ff(CACM“31:10,“October“1988,“1192-1201),Ž¡‘0|–ff"Random“Number“Generators:“Good“Ones“Are“Hard“To“Find."Ž¡‘0|–ffThe“authors“refer“to“this“generator“as“a“"minimallyŽ¡‘0|–ffacceptable"“or“"minimally“sufficient"“generator.Ž¡¡‘0|–ffstate“=“seedŽ¡‘0Algorithm:‘ ÌÌ|–ffnewstate“=“(a“*“oldstate)“mod“mŽ¡‘0|–ffoutput“=“state-1Ž¡¡‘0Comments:‘ ÌÌ|–ffThe“modulus“m“must“be“a“prime“for“this“class“of“generatorŽ¡‘0|–ff(as“opposed“to“the“more“common“power“of“two“modulus).Ž¡‘0|–ffFor“these“generators“we“use“m=2^31-1“(2,147,483,647).ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ é´ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffThe“choice“of“a“good“multiplier“a“is“crucial.Ž¤-ƒ¡‘/ºâParameters:‘ ÌÌ|–ffunsigned“int“m“//“modulusŽ¡‘/ºâ|–ffunsigned“int“a“//“multiplierŽ¡¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“state“//“a“"state“vector"“of“length“1Ž¡¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state-1).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“The“basic“algorithm“yields“output“in“the“range“[1,m-1].Ž¡‘/ºâ|–ffWe“subtract“1“to“return“output“in“the“range“[0,m-2]Ž¡‘/ºâ|–ff(i.e.“[0,2147483645].)Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“create:setStateFromSeed:˜[1,“2^32-1]Ž¡‘/ºâ|–ffcreate:setStateFromSeeds:“[1,“m-1]Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“these“generatorsŽ¡‘/ºâ|–ffhave“a“single“full“cycle“of“length“(m-1).Ž¡‘/ºâ|–ff(State=0“is“an“absorbing“state“which“will“not“normallyŽ¡‘/ºâ|–ffoccur;“we“avoid“setting“the“starting“state“to“0.)Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡‘/ºâ|–ff(I.e.“low“order“bits“should“not“have“small“cycles.)Ž¡‘/ºâ|–ffWith“m“prime,“this“generator“is“better“than“standard“LCG.Ž¡¡‘/ºâReference–fffor“|“Park“and“Miller,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâImplementation‘ ÌÌ|–ffThe“code“for“-getUnsignedMax“uses“a“trick“devised“byŽ¡‘/ºâcomment:‘+30|–ffSchrage“to“avoid“32-bit“overflow“when“calculating“theŽ¡‘/ºâ|–ffnext“state“(i.e.“using“q=m/a“and“r=m%a“as“auxiliaryŽ¡‘/ºâ|–ffvalues).“Using“64-bit“math“(long“long“integers)“is“moreŽ¡‘/ºâ|–ffstraightforward.“Unfortunagely,“on“x86“at“least,“thereŽ¡‘/ºâ|–ffis“a“35%“speed“penalty“for“doing“so.“The“output,“however,Ž¡‘/ºâ|–ffis“identical.“YMMV.Ž¡¡‘/ºâPMMLCGgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:’™4.715‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘5ÿü6.500“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“12.152“uSŽ¡¡‘/ºâRelative‘ffspeed:ŽŸ‘/ºâ|–ffSpeed“0.792“(time“1.263)“relative“to“MT19937“getUnsignedSampleŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ñü “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ---------------–ff|“-----------------------------------------------------------ŽŸ‘/ºâ---ŽºâŸG®ïhtml:ï html:ŸíÀPMMLCG1gen‘QëDocumentationŽ© âcïhtml:ï html:Ÿ¬„‘0ÂParameters:‘ ÌÌ|–ffa“=‘+3016,807Ž¤0²‘0|–ffm“=“2,147,483,647“(2^31-1)Ž¡¡‘0Reference–fffor“|“Park“and“Miller,“op.“cit.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(m-1).Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡‘0|–ffThese“parameters“have“been“extensively“tested“by“the“authors.Ž¡¡‘0Reference–fffor“|“Park“and“Miller,“op.“cit.Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŸ‡®ïhtml:ï html:ŸÀPMMLCG2gen‘QëDocumentationŽ¦ïhtml:ï html:Ÿ¬„‘0ÂParameters:‘ ÌÌ|–ffa“=‘+3048,271Ž¡‘0|–ffm“=“2,147,483,647“(2^31-1)Ž¡¡‘0Reference–fffor“|“Park“and“Miller,“op.“cit.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(m-1).Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡‘0|–ffThese“parameters“are“not“as“well“tested“as“PMMLCG1,Ž¡‘0|–ffbut“there's“reason“to“believe“they“may“be“better.Ž¡¡‘0Reference–fffor“|“Park“and“Miller,“op.“cit.Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŸ‡®ïhtml:ï html:ŸÀPMMLCG3gen‘QëDocumentationŽ¦ïhtml:ï html:Ÿ¬„‘0ÂParameters:‘ ÌÌ|–ffa“=‘+3069,621Ž¡‘0|–ffm“=“2,147,483,647“(2^31-1)Ž¡¡‘0Reference–fffor“|“Park“and“Miller,“op.“cit.ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹ ûn “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂchoice‘ffof‘ ÌÌ|Ž¤.I‘/ºâparameters:‘ ÌÌ|Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“length“(m-1).Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡‘/ºâ|–ffThese“parameters“are“not“as“well“tested“as“PMMLCG1,Ž¡‘/ºâ|–ffbut“there's“reason“to“believe“they“may“be“better.Ž¡¡‘/ºâReference–fffor“|“Park“and“Miller,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Žºâ©‡®ïhtml:ï html:Ÿª³ÀPMMLCG4gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª‘0ÂParameters:‘ ÌÌ|–ffa“=‘+3045,991Ž¡‘0|–ffm“=“2,147,483,647“(2^31-1)Ž¡¡‘0Reference–fffor“|“Pierre“L'Ecuyer“and“Terry“H.“Andres,Ž¡‘0choice–ffof‘ ÌÌ|“"A“Random“Number“Generator“Based“on“the“CombinationŽ¡‘0parameters:‘ ÌÌ|–ffof“Four“LCGs",“unpubl.Ž¡¡‘0|–ffThis“is“one“of“the“component“generators“of“their“CLCG4.Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(m-1).Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡¡‘0Reference–fffor“|“L'Ecuyer“and“Andres,“op.cit.Ž¡‘0output‘ffquality:‘ ÌÌ|Ž¦ïhtml:ï html:Ÿª³ÀPMMLCG5gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª‘0ÂParameters:‘ ÌÌ|–ffa“=‘%ÌÊ207,707Ž¡‘0|–ffm“=“2,147,483,543“(2^31-105)Ž¡¡‘0Reference–fffor“|“Pierre“L'Ecuyer“and“Terry“H.“Andres,Ž¡‘0choice–ffof‘ ÌÌ|“"A“Random“Number“Generator“Based“on“the“CombinationŽ¡‘0parameters:‘ ÌÌ|–ffof“Four“LCGs",“unpubl.Ž¡¡‘0|–ffThis“is“one“of“the“component“generators“of“their“CLCG4.Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(m-1).ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹!Z “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤NÖ‘/ºâÂOutput–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡¡‘/ºâReference–fffor“|“L'Ecuyer“and“Andres,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Žºâ©‡®ïhtml:ï html:ŸË@ÀPMMLCG6gen‘QëDocumentationŽŸ âcïhtml:ï html:ŸÊ¨‘0ÂParameters:‘ ÌÌ|–ffa“=‘%ÌÊ138,556Ž¡‘0|–ffm“=“2,147,483,423“(2^31-225)Ž¡¡‘0Reference–fffor“|“Pierre“L'Ecuyer“and“Terry“H.“Andres,Ž¡‘0choice–ffof‘ ÌÌ|“"A“Random“Number“Generator“Based“on“the“CombinationŽ¡‘0parameters:‘ ÌÌ|–ffof“Four“LCGs",“unpubl.Ž¡¡‘0|–ffThis“is“one“of“the“component“generators“of“their“CLCG4.Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(m-1).Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡¡‘0Reference–fffor“|“L'Ecuyer“and“Andres,“op.cit.Ž¡‘0output‘ffquality:‘ ÌÌ|Ž¦ïhtml:ï html:ŸË@ÀPMMLCG7gen‘QëDocumentationŽŸ âcïhtml:ï html:ŸÊ¨‘0ÂParameters:‘ ÌÌ|–ffa“=‘+3049,689Ž¡‘0|–ffm“=“2,147,483,323“(2^31-325)Ž¡¡‘0Reference–fffor“|“Pierre“L'Ecuyer“and“Terry“H.“Andres,Ž¡‘0choice–ffof‘ ÌÌ|“"A“Random“Number“Generator“Based“on“the“CombinationŽ¡‘0parameters:‘ ÌÌ|–ffof“Four“LCGs",“unpubl.Ž¡¡‘0|–ffThis“is“one“of“the“component“generators“of“their“CLCG4.Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(m-1).Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡¡‘0Reference–fffor“|“L'Ecuyer“and“Andres,“op.cit.Ž¡‘0output‘ffquality:‘ ÌÌ|Ž¦ïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹" Ã “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÑçåºâÀPMMLCG8gen‘QëDocumentationŽºâ© âcïhtml:ï html:Ÿ )s‘0ÂParameters:‘ ÌÌ|–ffa“=‘+3040,014Ž¤¡‘0|–ffm“=“2,147,483,563“(2^31-85)Ž¡¡‘0Reference–fffor“|“Pierre“L'Ecuyer“and“Serge“Cote,Ž¡‘0choice–ffof‘ ÌÌ|“"Implementing“a“Random“Number“Package“with“SplittingŽ¡‘0parameters:‘ ÌÌ|–ffFacilities,"“ACM“Trans.“Math.“Softw.“17“no“1“(March“1991).Ž¡¡‘0|–ffThis“is“one“of“the“component“generators“of“their“generator.Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(m-1).Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡¡‘0Reference–fffor“|“L'Ecuyer“and“Cote,“op.cit.Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŸ‡®ïhtml:ï html:Ÿ*ÀPMMLCG9gen‘QëDocumentationŽ¦ïhtml:ï html:Ÿ )s‘0ÂParameters:‘ ÌÌ|–ffa“=‘+3040,692Ž¡‘0|–ffm“=“2,147,483,399“(2^31-249)Ž¡¡‘0Reference–fffor“|“Pierre“L'Ecuyer“and“Serge“Cote,Ž¡‘0choice–ffof‘ ÌÌ|“"Implementing“a“Random“Number“Package“with“SplittingŽ¡‘0parameters:‘ ÌÌ|–ffFacilities,"“ACM“Trans.“Math.“Softw.“17“no“1“(March“1991).Ž¡¡‘0|–ffThis“is“one“of“the“component“generators“of“their“generator.Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“(m-1).Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“All“bits“should“be“safe.Ž¡¡‘0Reference–fffor“|“L'Ecuyer“and“Cote,“op.cit.Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŸ‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿ¡¿(./MWCA-Bgen.html)ŽŸ8äïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹#½ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÖ\’á³4ïï html:©¿(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(./PSWBgen.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹$ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½PSWBgen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffPSWB“--Ž¡‘0//‘32single–fflong“generator“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype–ffPSWBgen‘32“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“PSWBŽ¡¡‘0Description:‘ ÌÌ|–ffSubtract-with-Borrow“Congruential“GeneratorŽ¡‘0|‘™˜with–ffPrime“ModulusŽ¡¡‘0Reference:‘ ÌÌ|–ffGeorge“Marsaglia“and“Arif“Zaman,Ž¡‘0|–ff"A“New“Class“of“Random“Number“Generators",Ž¡‘0|–ffAnnals“of“Applied“Probability“vol“1“no“3“(1991),“462-480.Ž¡‘0|–ffSWB“is“an“improvement“on“the“Lagged“Fibonacci“generators.Ž¡¡‘0|–ffPSWB“is“an“improvement“on“SWB“in“that“the“use“of“a“primeŽ¡‘0|–ffmodulus“guarantees“a“single“full“cycle.Ž¡‘0|–ffIt's“slower,“of“course.Ž¡¡‘0|–ffstate“vector“=“f(seed)Ž¡‘0Algorithm:‘ ÌÌ|–ffstate_n“=“(state_(n-s)“-“state_(n-r)“-“carry)“mod“m;“r“>“sŽ¡‘0|–ffoutput“=“state_nŽ¡¡‘0|–ffThese“generators“use“a“basic“algorithm“of“the“formŽ¡‘0|–ffX_n“=“f(X_(n-r),X_(n-s))“mod“m;“r>sŽ¡‘0|–ffThe“function“f“is“typically“xor,“addition,“subtraction,Ž¡‘0|–ffmultiplication“or“subtraction“with“carry.“It“usesŽ¡‘0|–ffsimpler“math“than“a“basic“LCG,“but“keeps“a“larger“state.Ž¡¡‘0Implementation:‘ ÌÌ|–ffThe“state“vector“contains“the“generator's“r“most“recentŽ¡‘0|–ffoutputs“(X_n“..“X_(n-r)).“This“vector“is“initialized“fromŽ¡‘0|–ffan“LCG“generator“using“one“32-bit“seed“value.“AfterŽ¡‘0|–ffinitialization“we“throw“away“r*5“numbers“to“'prime'“theŽ¡‘0|–ffgenerator“(i.e.“make“sure“we“have“entered“a“closed“cycle.)Ž¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“r“//“long“lagŽ¡‘0|–ffunsigned“int“s“//“short“lagŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹% “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffunsigned“int“m“//“modulusŽ¤/¡¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“state[r]“//“state“vectorŽ¡‘/ºâ|–ffint“carry“//“carry“bitŽ¡¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,m-1]“may“be“returned.Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“r“seeds“in“[1,2^32-7]Ž¡‘/ºâ|–ffand“one“seed“in“[0,1]“(the“carry)Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“cycle“of“length“close“to“10^414.Ž¡¡‘/ºâ|–ffUnfortunately,“there“are“no“'jump-ahead'“or“'splitting'Ž¡‘/ºâ|–fffacilities“that“would“allow“us“to“jump“ahead“in“the“cycle,Ž¡‘/ºâ|–ffother“than“calling“the“generator“a“number“of“times.Ž¡¡‘/ºâOutput‘ffQuality:Ž©‘/ºâ|–ffMuch“better“than“other“Lagged“Fibonacci“generators,“such“asŽ¡‘/ºâ|–ffACG“and“SCG.Ž¡¡‘/ºâReference–fffor“|“Marsaglia“and“Zaman,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâPSWBgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*3.452‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–5.166“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“9.544“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž¦‘/ºâ|–ffSpeed“1.070“(time“0.933)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff|“-----------------------------------------------------------Ž¦‘/ºâ---Ž¡¡‘/ºâParameters:‘ ÌÌ|–ffr“=“43“//“long“lagŽ¡‘/ºâ|–ffs“=“22“//“short“lagŽ¡‘/ºâ|–ffm“=“2^32“-“5“//“modulus“(prime)Ž¡¡‘/ºâReference–fffor“|“Marsaglia,“op.“cit.Ž¡‘/ºâparameters:‘ ÌÌ|ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹&# “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ¤‘/ºâÂCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“cycle“of“length“close“to“10^414.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Marsaglia,“op.cit.,“p.“479Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦¿(./PMMLCG1-9gen.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(./RWC28gen.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹'+W “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½R‘ÿF7WC2,8gen‘/ClassesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffRWC2“--Ž¡‘0//–ffRWC8“("Mother")“--Ž¡‘0//‘32single–fflong“generator“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype–ffRWC2gen‘32“@endŽ¡‘0@deftype–ffRWC8gen‘32“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀR‘ÿe.WC2gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª8‘0ÂGenerator–ffname:‘ ÌÌ|“RWC2Ž¡¡‘0Description:‘ ÌÌ|–ff2-lag“Recursion-With-Carry“generatorŽ¡¡‘0Reference:‘ ÌÌ|–ffArticle“posted“to“Usenet“in“1994“by“George“Marsaglia,Ž¡‘0|–ff"The“Mother“of“all“Random“Number“Generators."Ž¡‘0|–ffSource“found“at“Ž¡‘0|–ffAlso“document“/papers/rwc1.ps“on“his“Diehard“CD-ROM,Ž¡‘0|–fffound“at“.Ž¡¡‘0Algorithm:– ÌÌ|›ffx[n]“=˜a*(x[n-1]+x[n-2])˜+˜carry˜%˜2^32Ž¡‘0|–ffcarry“=“a*(x[n-1]+x[n-2])“+“carry“/“2^32Ž¡¡‘0Comments:‘ ÌÌ|–ffThis“generator“is“a“2-lag“MWC“generatorŽ¡¡‘0Implementation:‘ ÌÌ|–ffThis“generator“is“implemented“using“64-bit“mathŽ¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“a“=“1,111,111,464“//“multiplierŽ¡¡‘0State:‘ ÌÌ|–ffunsigned“int“carry,x1,x2“//“state“vectorŽ¡¡‘0Output–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘0|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘0|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘0|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘0|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘0Output–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,unsignedMax]“=“[0,2^32-1].Ž¡¡‘0Valid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,“2^32-1]ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹(01 “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffUsing“create:setStateFromSeeds:“x1“and“x2:“[1,“2^32-1]Ž¤.l‘/ºâ|–ffThe“carry“can“only“be“[1,a-1].Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffThis“generator“is“claimed“to“have“a“period“>“2^92.Ž¡‘/ºâ|–ffIt“may“have“rho“sequences“up“to“length“r=2.Ž¡‘/ºâ|–ffIt“may“have“multiple“cycles“of“the“stated“period“length.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Marsaglia,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâRWC2gen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:’™7.445‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘5ÿü8.845“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“17.338“uSŽ¡¡‘/ºâRelative‘ffspeed:ŽŸ‘/ºâ|–ffSpeed“0.497“(time“2.013)“relative“to“MT19937“getUnsignedSampleŽºâŸ‡®ïhtml:ï html:ŸªÖÀR‘ÿe.WC8gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª>‘0ÂGenerator–ffname:‘ ÌÌ|“RWC8Ž¡¡‘0Description:‘ ÌÌ|–ff8-lag“Recursion-With-Carry“generatorŽ¡‘0|–ff("The“Mother“of“all“RNG's")Ž¡¡‘0Reference:‘ ÌÌ|–ffArticle“posted“to“Usenet“in“1994“by“George“Marsaglia,Ž¡‘0|–ff"The“Mother“of“all“Random“Number“Generators."Ž¡‘0|–ffSource“found“at“Ž¡‘0|–ffAlso“document“/papers/mwc1.ps“on“his“Diehard“CD-ROM,Ž¡‘0|–fffound“at“.Ž¡¡‘0Algorithm:‘ ÌÌ|–ffx“=“sum(ai*xi)“+“carry“mod“2^16Ž¡‘0|–ffy“=“sum(bi*yi)“+“carry“mod“2^16Ž¡‘0|–ffreturn“((x<<16)+y)Ž¡¡‘0Comments:‘ ÌÌ|–ffThis“generator“is“a“combination“of“2“16-bitŽ¡‘0|–ff8-lag“Recursion-With-Carry“generators.Ž¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“a[8]“=Ž¡‘0|–ffÇf“Â1941,“1860,“1812,“1776,“1492,“1215,“1066,“12013“ÇgŽ¡¡‘0Â|–ffunsigned“int“b[8]“=Ž¡‘0|–ffÇf“Â1111,“2222,“3333,“4444,“5555,“6666,“7777,‘ ÌÌ9272“ÇgŽ¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹)8, “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂState:‘ ÌÌ|–ffunsigned“short“m1[10],“m2[10]“//“state“vectorŽ¤c}¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,unsignedMax]“=“[0,2^32-1].Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,“2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:Ž¡‘/ºâ|‘32a–fftotal“of“18“16-bit“seeds“are“needed;Ž¡‘/ºâ|‘32each–ffxi“may“be“in“[1,“2^31-1].Ž¡‘/ºâ|‘32each–ffcarry“may“be“in“[1,“sum(multipliers)-1].Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffThis“generator“is“claimed“to“have“a“period“>“2^250.Ž¡‘/ºâ|–ffIt“may“have“rho“sequences“up“to“length“r“=“8.Ž¡‘/ºâ|–ffIt“may“have“multiple“cycles“of“the“stated“period“length.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Claimed“to“be“good.Ž¡¡‘/ºâReference–fffor“|“Marsaglia,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâRWC8gen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*14.649‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–16.400“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“31.915“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“0.252“(time“3.961)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--ŽŸ‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿc}¿(./PSWBgen.html)ŽŸ8äïhtml:ï html:¦’áøRïï html:Ÿc}(./Interface.html)ŽŸÕSïhtml:ï html:ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹*@$ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÖ\’á³4ï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽºâ© ïhtml:ï html:¤¿(./SCGgen.html)Ž¡‘0„¤ŽŽ¦ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹+HŽ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½SCGgen‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤0÷‘0Â//Ž¡‘0//–ffSCG“--Ž¡‘0//‘32single–fflong“random“number“generator,Ž¡‘0//‘32NOT–ffrecommended“for“serious“use;“included“forŽ¡‘0//‘32historical–ffreasons“(compatibility“with“earlier“releases).Ž¡‘0//Ž¡‘0@deftype–ffSCGgen‘ÿþ“@endŽŸ‘0„¤ŽŽ¤G®ïhtml:ï html:©íaÀUse–Qëof“this“generator“is“ïhtml:ï html:NO‘ÿOT“RecommendedŽŸ^5‘0„¤ŽŽ¡ïhtml:ï html:¦DocumentationŽŸ ¢Âïhtml:ï html:Ÿìj‘0ÂGenerator–ffname:‘ ÌÌ|“SCGŽ¤0÷¡‘0Description:‘ ÌÌ|–ffSubtractive“Congruential“GeneratorŽ¡¡‘0Reference:‘ ÌÌ|–ffSCG“is“an“often“used“algorithm,“mentioned“in“Knuth,Ž¡‘0|–ffNumerical“Recipes,“etc.Ž¡¡‘0|–ffstate“vector“=“f(seed)Ž¡‘0Algorithm:‘ ÌÌ|–ffstate_n“=“(state_(n-r)“-“state_(n-s))“mod“10^9;“r“>“sŽ¡‘0|–ffoutput“=“state_nŽ¡¡‘0|–ffSCG“is“in“the“Lagged“Fibonacci“class“of“generators.Ž¡‘0|–ffThese“generators“use“a“basic“algorithm“of“the“formŽ¡‘0|–ffX_n“=“f(X_(n-r),X_(n-s))“mod“m;“r>sŽ¡‘0|–ffThe“function“f“is“typically“xor,“addition,“subtraction,Ž¡‘0|–ffmultiplication“or“subtraction“with“carry.“It“usesŽ¡‘0|–ffsimpler“math“than“a“basic“LCG,“but“keeps“a“larger“state.Ž¡¡‘0Implementation:‘ ÌÌ|–ffThe“state“vector“contains“the“generator's“r“most“recentŽ¡‘0|–ffoutputs“(X_n“..“X_(n-r)).“This“vector“is“initialized“fromŽ¡‘0|–ffan“LCG“generator“using“one“32-bit“seed“value.“AfterŽ¡‘0|–ffinitialization“we“throw“away“r*5“numbers“to“'prime'“theŽ¡‘0|–ffgenerator“(i.e.“make“sure“we“have“entered“a“closed“cycle.)Ž¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“r“//“long“lagŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹,Jï “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffunsigned“int“s“//“short“lagŽ¤.Œ‘/ºâ|–ffunsigned“int“m“//“modulusŽ¡¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“state[r]“//“state“vectorŽ¡¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,10^9-1]“may“be“returnedŽ¡‘/ºâ|–ff(i.e.“[0,999999999].)Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“[1,999999998]Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“these“generatorsŽ¡‘/ºâ|–ffhave“a“cycle“of“length“about“2^r.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Low“order“bits“are“poor,“and“there“are“other“problems.Ž¡‘/ºâ|–ffSWB“is“a“better“generator“in“the“same“class,“and“it“isŽ¡‘/ºâ|–ffonly“slightly“slower.Ž¡¡‘/ºâReference–fffor“|“Knuth,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâSCGgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*3.328‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–5.058“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“9.274“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“1.111“(time“0.900)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff|“-----------------------------------------------------------Ž¦‘/ºâ---Ž¡¡‘/ºâParameters:‘ ÌÌ|–ffr“=“55Ž¡‘/ºâ|–ffs“=“24Ž¡‘/ºâ|–ffm“=“10^9Ž¡¡‘/ºâReference–fffor“|Ž¡‘/ºâparameters:‘ ÌÌ|Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“a“single“full“cycle“of“length“~“2^r.Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹-R² “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂOutput–ffQuality:‘ ÌÌ|“Low-order“bits“are“poor.Ž¤¡‘/ºâReference–fffor“|“Knuth,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦¿(./RWC28gen.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(./SWB1-3gen.html)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹.Z… “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½SWB1-3gen‘/ClassesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffSWB1,“SWB2,“SWB3“--Ž¡‘0//‘32single–fflong“generators“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype–ffSWBgen‘32“@endŽ¡‘0@deftype–ffSWB1gen‘™˜“@endŽ¡‘0@deftype–ffSWB2gen‘™˜“@endŽ¡‘0@deftype–ffSWB3gen‘™˜“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀGeneral‘QëDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“SWBŽ¡¡‘0Description:‘ ÌÌ|–ffSubtract-with-Borrow“Congruential“GeneratorŽ¡¡‘0Reference:‘ ÌÌ|–ffGeorge“Marsaglia“and“Arif“Zaman,Ž¡‘0|–ff"A“New“Class“of“Random“Number“Generators",Ž¡‘0|–ffAnnals“of“Applied“Probability“vol“1“no“3“(1991),“462-480.Ž¡‘0|–ffSWB“is“an“improvement“on“the“Lagged“Fibonacci“generators.Ž¡¡‘0|–ffstate“vector“=“f(seed)Ž¡‘0Algorithm:‘ ÌÌ|–ffstate_n“=“(state_(n-s)“-“state_(n-r)“-“carry)“mod“2^32;“r“>“sŽ¡‘0|–ffoutput“=“state_nŽ¡¡‘0|–ffThese“generators“use“a“basic“algorithm“of“the“formŽ¡‘0|–ffX_n“=“f(X_(n-r),X_(n-s))“mod“m;“r>sŽ¡‘0|–ffThe“function“f“is“typically“xor,“addition,“subtraction,Ž¡‘0|–ffmultiplication“or“subtraction“with“carry.“It“usesŽ¡‘0|–ffsimpler“math“than“a“basic“LCG,“but“keeps“a“larger“state.Ž¡¡‘0Note:‘ ÌÌ|–ffThis“generator“relies“on“controlled“overflow“at“32“bits.Ž¡‘0|–ffThis“requires“that“unsigned“be“a“32bit“value“that“followsŽ¡‘0|–ffANSI“C“rules.Ž¡¡‘0Implementation:‘ ÌÌ|–ffThe“state“vector“contains“the“generator's“r“most“recentŽ¡‘0|–ffoutputs“(X_n“..“X_(n-r)).“This“vector“is“initialized“fromŽ¡‘0|–ffan“LCG“generator“using“one“32-bit“seed“value.“AfterŽ¡‘0|–ffinitialization“we“throw“away“r*5“numbers“to“'prime'“theŽ¡‘0|–ffgenerator“(i.e.“make“sure“we“have“entered“a“closed“cycle.)Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹/^ç “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂParameters:‘ ÌÌ|–ffunsigned“int“r“//“long“lagŽ¤0¾‘/ºâ|–ffunsigned“int“s“//“short“lagŽ¡¡‘/ºâState:‘ ÌÌ|–ffunsigned“int“state[r]“//“state“vectorŽ¡‘/ºâ|–ffint“carry“//“carry“bitŽ¡¡‘/ºâOutput–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).Ž¡‘/ºâ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¡‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,2^32-1]“may“be“returnedŽ¡‘/ºâ|–ff(i.e.“[0,4294967295].)Ž¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜[1,2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“r“seeds“in“[1,2^32-2]Ž¡‘/ºâ|–ffand“one“seed“in“[0,1]“(the“carry)Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“these“generatorsŽ¡‘/ºâ|–ffhave“a“number“of“long“cycles,“up“to“10^354“in“length.Ž¡‘/ºâ|–ffUNFORTUNATELY“there“is“no“way“to“pick“differentŽ¡‘/ºâ|–ffcycles,“nor“any“easy“way“to“'jump“ahead'“in“theŽ¡‘/ºâ|–ffchosen“cycle“(other“than“calling“-getUnsignedSampleŽ¡‘/ºâ|–ffa“number“of“times).Ž¡¡‘/ºâOutput‘ffQuality:Ž©‘/ºâ|–ffMuch“better“than“other“Lagged“Fibonacci“generators,“such“asŽ¡‘/ºâ|–ffACG“and“SCG.Ž¡¡‘/ºâReference–fffor“|“Marsaglia“and“Zaman,“op.cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž¡¡‘/ºâSWBgen–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâspeed:‘ ÌÌ|‘32-getUnsignedSample:‘|3*3.285‘ffuSŽ¡‘/ºâ|‘32-getFloatSample,–ffgetDoubleSample:‘0™–5.057“uSŽ¡‘/ºâ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“9.209“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž¦‘/ºâ|–ffSpeed“1.126“(time“0.888)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff|“-----------------------------------------------------------Ž¦‘/ºâ---ŽºâŸG®ïhtml:ï html:Ÿí(ÀSWB1gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿ¬‘0ÂParameters:‘ ÌÌ|–ffr“=“37ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹0g) “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffs“=“24Ž¤~>¡‘/ºâReference–fffor“|“Marsaglia,“op.“cit.Ž¡‘/ºâparameters:‘ ÌÌ|Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘/ºâ|–ffhas“64“cycles“of“length“10^354Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Marsaglia,“op.cit.,“p.“479Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Žºâ©‡®ïhtml:ï html:Ÿú¨ÀSWB2gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿú‘0ÂParameters:‘ ÌÌ|–ffr“=“24Ž¡‘0|–ffs“=“19Ž¡¡‘0Reference–fffor“|“Marsaglia,“op.“cit.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“1536“cycles“of“length“10^228Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘0Reference–fffor“|“Marsaglia,“op.cit.,“p.“479Ž¡‘0output‘ffquality:‘ ÌÌ|Ž¦ïhtml:ï html:Ÿú¨ÀSWB3gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿú‘0ÂParameters:‘ ÌÌ|–ffr“=“21Ž¡‘0|–ffs“=‘ ÌÌ6Ž¡¡‘0Reference–fffor“|“Marsaglia,“op.“cit.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“192“cycles“of“length“10^200Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘0Reference–fffor“|“Marsaglia,“op.cit.,“p.“479Ž¡‘0output‘ffquality:‘ ÌÌ|ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹1o· “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:©\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:Ÿ¿(./SCGgen.html)ŽŸ8äïhtml:ï html:¦’áøRïï html:Ÿ(./Interface.html)ŽŸÕSïhtml:ï html:¦’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¤(./TGFSRgen.html)Ž¡‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹2uO “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½TGFSRgen‘/ClassesŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤.f‘0Â//Ž¡‘0//–ffTT403,“TT775,“TT800“--Ž¡‘0//‘32single–fflong“generators“recommended“for“use.Ž¡‘0//Ž¡‘0@deftype‘ffTGFSRgen‘™˜‘ ÌÌ@endŽ¡‘0@deftype–ffTT403gen‘ÿþ“@endŽ¡‘0@deftype–ffTT775gen‘ÿþ“@endŽ¡‘0@deftype–ffTT800gen‘ÿþ“@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸêÐÀGeneral‘QëDocumentationŽŸ ¢Âïhtml:ï html:ŸéÙ‘0ÂGenerator–ffname:‘ ÌÌ|“TGFSRŽ¡¡‘0Description:‘ ÌÌ|–ffTwisted“GFSR“generatorŽ¡¡‘0Reference:‘ ÌÌ|–ffMakoto“Matsumoto“and“Yoshiharu“Kurita,Ž¡‘0|–ff"Twisted“GFSR“Generators“II".Ž¡‘0|–ffACM“TOMACS,“vol“4“no“3“July“1994“pp.“254-266.Ž¡‘0|–ffAmended“by“M.“Matsumoto,“July“8“1996.Ž¡¡‘0|Ž¡‘0Algorithm:‘ ÌÌ|Ž¡‘0|Ž¡¡‘0Comments:‘ ÌÌ|Ž¡¡‘0Implementation:‘ ÌÌ|Ž¡¡‘0Parameters:‘ ÌÌ|–ffunsigned“int“w“//“word“lengthŽ¡‘0|–ffunsigned“int“N“//“size“of“state“arrayŽ¡‘0|–ffunsigned“int“M“//“lagŽ¡‘0|–ffunsigned“int“s“//“'magic“vector'Ž¡‘0|–ffunsigned“int“t“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“b“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“c“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“a“//‘™˜"‘ÿþ"Ž¡¡‘0State:‘ ÌÌ|–ffunsigned“int“state[N]“//“state“vectorŽ¡¡‘0Output–fftypes:‘ ÌÌ|“unsigned“int“(we“return“the“current“state).ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹3y/ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–fffloat“in“[0.0,1.0)“using“1“iteration“of“the“generator.Ž¤/Ž‘/ºâ|–ffdouble“in“[0.0,1.0)“using“1“or“2“iterations“of“the“generator.Ž¡‘/ºâ|–fflong“double“in“[0.0,1.0)“using“2“iterations“of“the“generator.Ž¡‘/ºâ|–ff(See“the“implementation“file“for“more“details.)Ž¡¡‘/ºâOutput–ffrange:‘ ÌÌ|“Any“number“in“the“range“[0,2^w-1]“may“be“returnedŽ¡¡‘/ºâValid–ffseeds:› ÌÌ|“Using“create:setStateFromSeed:˜in“[1,2^32-1]Ž¡‘/ºâ|–ffUsing“create:setStateFromSeeds:“in“[1,2^w-1].Ž¡¡‘/ºâCycles:‘ ÌÌ|–ffWith“properly“chosen“parameters,“these“generatorsŽ¡‘/ºâ|–ffhave“a“single“cycle“of“length“2^(w*N)“-1.Ž¡¡‘/ºâOutput–ffQuality:‘ ÌÌ|“Good.Ž¡¡‘/ºâReference–fffor“|“Matsumoto“and“Kurita,“op.“cit.Ž¡‘/ºâoutput–ffquality:‘ ÌÌ|“Also“recommended“by“P.“L'Ecuyer“(private“communication).Ž¡¡‘/ºâTT403gen,–ff|“On“a“486/66,“the“following“approximate“measures“were“obtained:Ž¡‘/ºâTT775gen,–ff|‘32-getUnsignedSample:’™4.654“uSŽ¡‘/ºâTT800gen–ff|‘32-getFloatSample,“getDoubleSample:‘5ÿü6.430“uSŽ¡‘/ºâspeed:‘ ÌÌ|‘32-getFatDoubleSample,–ffgetLongDoubleSample:“11.953“uSŽ¡¡‘/ºâRelative‘ffspeed:Ž©‘/ºâ|–ffSpeed“0.795“(time“1.259)“relative“to“MT19937“getUnsignedSampleŽ¡‘/ºâ---------------–ff.“-----------------------------------------------------------Ž¦‘/ºâ--ŽºâŸG®ïhtml:ï html:ŸëøÀTT403gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿ«`‘0ÂParameters:‘ ÌÌ|–ffunsigned“int“w=31“//“word“lengthŽ¡‘0|–ffunsigned“int“N=13“//“size“of“state“arrayŽ¡‘0|–ffunsigned“int“M=2“//“lagŽ¡‘0|–ffunsigned“int“s=8“//“'magic“vector'Ž¡‘0|–ffunsigned“int“t=14“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“b=0x102d1200“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“c=0x66e50000“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“a=0x6b5eccf6“//‘™˜"‘ÿþ"Ž¡¡‘0Reference–fffor“|“Matsumoto“and“Kurita,“op.“cit.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“2^403“-1.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Good.“Parameters“chosen“on“the“basis“of“theoryŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹4Ÿ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ|–ffand“empirical“testing.Ž¤.I¡‘/ºâReference–fffor“|“Matsumoto“and“Kurita,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Žºâ©‡®ïhtml:ï html:Ÿª³ÀTT775gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª‘0ÂParameters:‘ ÌÌ|–ffunsigned“int“w=31“//“word“lengthŽ¡‘0|–ffunsigned“int“N=25“//“size“of“state“arrayŽ¡‘0|–ffunsigned“int“M=8“//“lagŽ¡‘0|–ffunsigned“int“s=6“//“'magic“vector'Ž¡‘0|–ffunsigned“int“t=14“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“b=0x1abd5900“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“c=0x776a0000“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“a=0x6c6cb38c“//‘™˜"‘ÿþ"Ž¡¡‘0Reference–fffor“|“Matsumoto“and“Kurita,“op.“cit.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“2^775“-1.Ž¡¡‘0Output–ffQuality:‘ ÌÌ|“Good.“Parameters“chosen“on“the“basis“of“theoryŽ¡‘0|–ffand“empirical“testing.Ž¡¡‘0Reference–fffor“|“Matsumoto“and“Kurita,“op.“cit.Ž¡‘0output‘ffquality:‘ ÌÌ|Ž¦ïhtml:ï html:Ÿª³ÀTT800gen‘QëDocumentationŽŸ âcïhtml:ï html:Ÿª‘0ÂParameters:‘ ÌÌ|–ffunsigned“int“w=32“//“word“lengthŽ¡‘0|–ffunsigned“int“N=25“//“size“of“state“arrayŽ¡‘0|–ffunsigned“int“M=7“//“lagŽ¡‘0|–ffunsigned“int“s=7“//“'magic“vector'Ž¡‘0|–ffunsigned“int“t=15“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“b=0x2b5b2500“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“c=0xdb8b0000“//‘™˜"‘ÿþ"Ž¡‘0|–ffunsigned“int“a=0x8ebfd028“//‘™˜"‘ÿþ"Ž¡¡‘0Reference–fffor“|“Matsumoto“and“Kurita,“op.“cit.Ž¡‘0parameters:‘ ÌÌ|Ž¡¡‘0Cycles:‘ ÌÌ|–ffWith“the“chosen“parameters,“this“generatorŽ¡‘0|–ffhas“a“single“full“cycle“of“length“2^800“-1.Ž¡ŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹5ˆj “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂOutput–ffQuality:‘ ÌÌ|“Good.“Parameters“chosen“on“the“basis“of“theoryŽ¤‘/ºâ|–ffand“empirical“testing.Ž¡¡‘/ºâReference–fffor“|“Matsumoto“and“Kurita,“op.“cit.Ž¡‘/ºâoutput‘ffquality:‘ ÌÌ|Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:ï html:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦¿(./SWB1-3gen.html)ŽŸ8äïhtml:ï html:Ÿ\’áøRïï html:¦(./Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¦(./Prot.html#ProbabilityDist)Ž¦‘0„¤ŽŽ¡ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-26ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹6ß “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½RandomBitDistrib•Üution‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤Hå‘0Â//Ž¡‘0//–ffRandomBitDistribution“--Ž¡‘0//‘32A–ffgenerator“that“returns“uniformly“distributed“single“bit“valuesŽ¡‘0//‘32(i.e.–fffair“coin“tosses).Ž¡‘0//Ž¡‘0@deftype–ffRandomBitDist“Ž¡‘0USINGŽ¡‘0-–ff(BOOL)“getCoinToss;Ž¡‘0@endŽŸ‘0„¤ŽŽŸG®ïhtml:ï html:ŸOÀDocumentationŽŸ ¢Âïhtml:ï html:ŸX‘0ÂName:‘ ÌÌ|‘ffRandomBitDistributionŽ¡¡‘0Description:‘ ÌÌ|–ffDistribution“returning“YES“and“NO“with“equal“probabilityŽ¡¡‘0Algorithm:‘ ÌÌ|–ffExtract“a“middle“bit“from“an“unsigned“random“numberŽ¡¡‘0Reference:‘ ÌÌ|‘ff(none)Ž¡¡‘0Parameters:‘ ÌÌ|‘ff(none)Ž¡¡‘0State:‘ ÌÌ|–ffunsigned“long“long“int“currentCountŽ¡¡‘0RandomBitDist–ff|“On“a“486/66,“the“following“measures“were“obtained,Ž¡‘0speed:‘ ÌÌ|–ffusing“MT19937“as“the“underlying“generator:Ž¡¡‘0|‘ ÌÌ-getBooleanSample:’†ÿö5.656‘ffuSŽ¡‘0|‘ ÌÌ-average–ff#“of“generator“calls“per“variate:“1.000“(U)Ž¡‘0|‘ ÌÌ-distribution–ffnet“time:‘kÿø1.958“uSŽ¡¡‘0Relative‘ffspeed:Ž©‘0|–ffSpeed“0.654“(time“1.529)“relative“to“MT19937“getUnsignedSampleŽ¡‘0---------------–ff.“-----------------------------------------------------------Ž¦‘0--ŽŸ‘0„¤ŽŽŸ ïhtml:ï html:Ÿ\’áøRïï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:¤ ¿(Interface.html)ŽŸÕSïhtml:ï html:Ÿ\’áøRï>PSfile="eps/next.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:ï html:¤(BernoulliDist.html)Ž¡‘0„¤ŽŽŸ ïhtml:ï html:¤‘0¾Marcus–?ýG.“Daniels“ïhtml:ï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŸ8äïhtml:ï html:Ÿ Ç‘0¿Last‘?ýmodified:‘ ú1998-01-10ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹8›@ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Ber°mnoulliDistrib•Üution‘/ClassŽŸq'‘0„¤ŽŽŸ ïhtml:ï html:¤0ù‘0Â//Ž¡‘0//–ffBernoulliDistribution“--Ž©‘0distribution–ffreturning“YES“with“given“probability“pŽ¡‘0//Ž¡‘0@deftype–ffBernoulliDist“Ž¡‘0CREATINGŽ¡‘0+–ffcreate:“aZone“setGenerator:“generatorŽ¡’†f`setProbability:–ff(double)“p;Ž¡‘0+–ffcreate:“aZone“setGenerator:“generatorŽ¡‘0setVirtualGenerator:–ff(unsigned)“vGenŽ¡’†f`setProbability:–ff(double)“p;Ž¡‘0USINGŽ¡‘0-–ffsetProbability:“(double)“p;Ž¡‘0-–ff(double)“getProbability;Ž¡‘0-–ff(BOOL)‘+30getSampleWithProbability:“(double)“p;Ž¡‘0@endŽŸ‘0„¤ŽŽŸG®ïhtml:ŸícÀDocumentationŽŸ ¢Âïhtml:Ÿìl‘0ÂName:‘ ÌÌ|‘ffBernoulliDistributionŽ¡¡‘0Description:‘ ÌÌ|–ffDistribution“returning“binary“value“YES“with“probability“pŽ¡¡‘0Algorithm:‘ ÌÌ|–ffRejection“methodŽ¡¡‘0Reference:‘ ÌÌ|–ffCode“contributed“by“Barry“McMullinŽ¡¡‘0Parameters:‘ ÌÌ|–ffdouble“ProbabilityŽ¡¡‘0State:‘ ÌÌ|–ffunsigned“long“long“int“currentCountŽ¡¡‘0BernoulliDist–ff|“On“a“486/66,“the“following“measures“were“obtained,Ž¡‘0speed:‘ ÌÌ|–ffusing“MT19937“as“the“underlying“generator:Ž¡¡‘0|‘ ÌÌ-getBooleanSample:’†ÿö8.156‘ffuSŽ¡‘0|‘ ÌÌ-average–ff#“of“generator“calls“per“variate:“1.000“(tD)Ž¡‘0|‘ ÌÌ-distribution–ffnet“time:‘kÿø2.654“uSŽ¡¡‘0Relative‘ffspeed:Ž¦‘0|–ffSpeed“0.453“(time“2.206)“relative“to“MT19937“getUnsignedSampleŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹9ž “ºâ ýxºâïcolor push Blackïhtml:ŸüfdŽŽŽ’Ôï color popŽŽ ^ ýÐ‘/ºâÂ---------------–ff.“-----------------------------------------------------------ŽŸ‘/ºâ--Ž©‘/ºâ„¤ŽŽºâ¤ ïhtml:Ÿ\’áøRï>PSfile="eps/prev.eps" llx=298 lly=373 urx=314 ury=389 rwi=160 ŽŽ¡ïhtml:¦¿(./RandomBitDist.html)ŽŸÕSïhtml:Ÿ\’áøRï