Methods

A method is similar to a subroutine in other languages. A method is a section of source code that accepts parameters as input, performs a specific function, and then returns a result value. Methods in Spin are declared with PUB, for public methods, and PRI, for private methods. There must be at least one public method in every Spin object. Propeller Application execution begins with the first public method in the application’s top object.

Yes, there is a "reference" limit of 255 per object.

For each individual object, the number of methods plus the number of included objects in its OBJ block cannot exceed 255.

Reference Limit Per Object: Method Count + Object Count ≤ 255

Examples:

• An object can have 255 methods, but upon creating a 256th method, or including 1 object in an OBJ block, it will get a compile error.
• An object can have 1 method (the minimum required) and include 254 objects, but upon creating an additional method or including an additional object, it will get a compile error.
• If an object has 128 methods, it has room to include a combination of 127 more methods and objects.

Note that this limit applies to each object individually. For a parent object, each included child object only counts as "1" towards this limit, regardless of how many methods or objects that child object uses. So, even if an object has reached its limit of 255 combined methods and included objects, it itself can be included by another object without error because that parent object has its own limit of 255 combined methods and included objects.

Spin methods are like subroutines in that they contain the instructions to perform a specific process, and can be used over and over again as needed. Unlike subroutines in languages like PBASIC, methods can be passed parameters; that is, a set of temporary values that are used in the execution of that instance of the subroutine, without having to define variables or constants globally in the program.

Private methods (declared with PRI) can only be accessed from inside of the object where they are defined. Public (PUB) methods can be accessed from inside and outside the defining object, and are used to create interfaces between objects. From inside an object, it's public and private methods can be accessed, or "called," by simply referencing the method's name. From outside an object, to call its public methods, the calling object must first symbolically declare the target object in an OBJ block.

OBJ
  Clk : "Clock" 

In this case, Clk is the symbolic nickname this object will use when referring to the Clock object. Then, the desired public method can be accessed by name, in the form Object.Method where Object is the symbolic nickname given in the declaration and Method is one of the object's public methods.

PUB Main  
  Clk.PauseMSec(100)       'Pause form 100 milliseconds

No. Indenting the lines that are part of the method just makes it easier to read. Indenting IS necessary to define other types of code blocks, such as REPEAT and IF.

It depends on what type of object it is.

Most objects are building block objects, so there is no designated method that is executed first, automatically. Instead, the calling object chooses any of the available public methods to execute first.

A top object is different; the very first public method in a top object will automatically be executed by the application upon start up. This becomes the application's initial entry point. It doesn't matter what that method is called, but developers often call it "main."

This happens naturally, you do not have to end a method with any specific command or with a blank line. The compiler knows that a method is complete when it finds the beginning of the next block declaration (CON, DAT, OBJ, PRI, PUB, or VAR) or when it reaches the end of the program listing. The compiler always internally inserts a RETURN command at the end of methods, so there's no need to do so yourself unless you wish to return a value other than what's in the RESULT variable at that point in code. By convention, it's common to insert one or two blank lines between methods to enhance readability.

The compiler always inserts a RETURN command at the end of methods- so if execution reaches the end of the method, it simply returns to the caller, passing back the current value of the local RESULT variable as it returns.

If execution reaches the end of the top object's first method, the return from that method results in the Application Cog (usually Cog 0) terminating. This may or may not equate to the Propeller chip shutting down, as some applications end with the termination of Cog 0 while others carry on through additional cogs that were started as a result of application activity.

Method names and the purposes they serve are entirely the choice of the developer, but following certain conventions is recommended for methods that serve the roles of object configuration (Init) and cog management (Start and Stop).

These conventions serve a familiar "getting started" purpose to new users of the object.

By convention developers name a method "Init" (short for "initial" or "initialization") when it serves as the configuration method of a building block object. An object with an Init method may or may not also include Start and Stop methods.

By convention, developers name a method "Start" when it serves as the cog launch manager of a building block object. An object with a Start method should also have a Stop method, and occasionally an Init method as well.

Similarly, developers name a method "Stop" when it serves as the cog termination manager of a building block object. An object with a Stop method should also have a Start method, and occasionally an Init method as well.

Example Start and Stop Methods:

VAR
  byte   Cog                        'Cog (ID+1) that is started by this object

PUB Start({ParamaterList}): Success
{Launch another cog for parallel processing}
  Stop
  Success := (Cog := cognew({SpinMethodOrAsmAddr}, {StackAddrOrPARValue}) + 1) > 0

PUB Stop
{Terminate managed cog, if any}
  if Cog
    cogstop(Cog~ -1)

In this example, the Start method calls Stop to terminate any previously started cog (in case Start gets called multiple times) and then launches a new cog with COGNEW. It stores the Cog ID returned by COGNEW, plus 1, into the Cog variable to record the cog-launch status and simplify decision logic in Stop. It uses a comparison operation (> 0) to set the Success result variable to True if a cog was started; False otherwise.

The Stop method checks if the Cog variable is True (any non-zero value), and if so, terminates the cog that this object had started. The expression Cog~ -1 first subtracts 1 from Cog (delivering to COGSTOP the exact ID of the cog that was launched) then clears Cog to 0 (False) so successive calls to Stop don't inadvertently terminate innocent cogs.

Often developers will name the first method of a top object "Main" because it serves as the application starting point and the highest-level coordinator of application function.

Main is not a reserved word in Spin; special status is given only to the first public method in the top object of a Propeller Application.