÷ƒ’À;è TeX output 1998.01.28:1946‹ÿÿÿÿ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIyóÓߌ˜¼j ptmb7t½Def‘ÿ{Jobj‘/LibraryŽŸq'‘0„¤ŽŽ¤ ïhtml:ï html:Ÿ´‘0óÓߌ˜ ptmb7t¿Documentation–and“Implementation“StatusŽŸ‘0„¤ŽŽ©G®ïhtml:ï html:Ÿ óÓߌ˜G® ptmb7tÀOv•ÓÅer“viewŽŸ«Óó3{Ù ptmr7t¼The–}¦defobj“library“supports“the“style“of“object-oriented“programming“that“is“used“throughout“Swægarm.‘‰It“de nes“aŽ¡speci c–ݘstyle“for“using“the“ObjectišÀvÙ e“C‘Ý€language“that“includes“its“o˜wn“standard“con™ŸvÙ entions“for“creating“objects“andŽ¡for–€storage“allocation,“error“handling,“and“debÌÐugging“support.ŽŸ ˆmïhtml:ï html:ŸÕÈ‘0„¤ŽŽ¦ïhtml:ï html:Ÿ ÀDocumentationŽ¤«Ó¼The–€defobj“library“folloÀws“the“Swægarm“ïhtml:ï html:óßêï html:Ž¡(defobj/library.html)Ž¤ Mž¼.‘˜It–€has“folloÀwing“standard“sections“of“documentation:ŽŸ*8ïhtml:ï html:Ÿ ïhtml:ï html:©ïhtml:ï html:Ÿ #f‘0ïcolor push Blackó\ùð pzdrÁlï color popŽŽ‘:ïhtml:ï html:¾Usage‘?ýGuideïhtml:ï html:Ž¡‘0(defobj/guide.html)ŽŸ8äï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óßêï html:‘¼rïhtml:ï html:Ž¡‘0(mailto:mgd@santafe.edu)ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹* “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆï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™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:ŸóÓߌ˜ff ptmb7tÃ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“De nitionsŽŸ¾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ó0ˆÛ pcrr7tÄ/*Ž¡‘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ŽŽŒ‹1¡ “ºâ ý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ŽŽŒ‹:󠓺â ý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ŽŽŒ‹ Jœ “ºâ ý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ŽŽŒ‹ Xk “ºâ ý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ŽŽŒ‹ i¢ “ºâ ý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ŽŽŒ‹ l “ºâ ý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ŽŽŒ‹ z  “ºâ ý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ŽŽŒ‹Ÿ8 “ºâ ý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ŽŽŒ‹¢ “ºâ ý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ŽŽŒ‹­¾ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ žâÀNameŽŸªóïhtml:ï html:Ÿ"–ÃDe nedObject–™™{“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ŽŽŒ‹² “ºâ ý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:Ÿ¿&ÃDe ned‘™™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:Ÿ¿&ÃDe ned‘™™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ŽŽŒ‹¹ë “ºâ ý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ŽŽŒ‹Äà“ºâ ý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ŽŽŒ‹Ì™ “ºâ ý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:Ÿ_“ÃDe ned‘™™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:Ÿ&¯ÃDe ned‘™™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ŽŽŒ‹Ö “ºâ ý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ŽŽŒ‹âZ “ºâ ý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ŽŽŒ‹òÒ “ºâ ý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ŽŽŒ‹ø “ºâ ý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ŽŽŒ‹ “ºâ ý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ŽŽŒ‹3 “ºâ ý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ŽŽŒ‹ 4ô “ºâ ý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ŽŽŒ‹"P  “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:Ÿ žâÀNameŽŸªóïhtml:ï html:Ÿ„°ÃSymbol–™™{“object“de ned“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ŽŽŒ‹#Qê “ºâ ý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ŽŽŒ‹$Zx “ºâ ý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ŽŽŒ‹%_󠓺â ý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ŽŽŒ‹&h “ºâ ý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ŽŽŒ‹'u? “ºâ ý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ŽŽŒ‹(z’ “ºâ ý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ŽŽŒ‹)„¬ “ºâ ý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ŽŽŒ‹*Ž” “ºâ ý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ŽŽŒ‹+— “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Module–/De nition“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ŽŽŒ‹,¦$ “ºâ ý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“De nitionsŽŸ¾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ŽŽŒ‹-´9 “ºâ ý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ŽŽŒ‹.ÃÔ “ºâ ý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ŽŽŒ‹/Ì€ “ºâ ý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ŽŽŒ‹0Û “ºâ ý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ŽŽŒ‹1é] “ºâ ý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ŽŽŒ‹2úÜ “ºâ ý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ŽŽŒ‹3ü “ºâ ý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ŽŽŒ‹4_ “ºâ ýxºâïcolor push Blackïhtml:ï html:ŸüfdŽŽŽ’Ôï color popŽŽ ^ºâ ýÆïhtml:ï html:ŸIy½Def‘ÿ{Jobj–/Library:‘m™Global“De nitionsŽŸ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“de nitionŽŸê”ïhtml:ï html:ŸG»ÃSynopsisŽŸ ‘ýïhtml:ï html:Ÿ –‘0Ä//Ž¤ „;‘0//–fffunc_t“--“function“pointer“typeŽ¡‘0//Ž¡‘0typedef–ffvoid“(*func_t)(“void“);ŽŽŸ*ºâïcolor push Black’Ôï color popŽŽŒ‹5 > “ºâ ý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ŽŽŒ‹6e “ºâ ý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ŽŽŒ‹7n “ºâ ý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ŽŽŒ‹8)” “ºâ ý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ŽŽŒ‹92| “ºâ ý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ŽŽŒ‹:;x “ºâ ý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ŽŽŒø>Fƒ’À;è—T~Óºâ :ó0ˆÛ pcrr7tóÓߌ˜ff ptmb7tóßê