Modifying v3.1 protocols

In addition to the other modifications one needs to make to translate an existing protocol from v3.1 to v3.2, one should make the following modifications with respect to reference counts:

• foo_open should not increment the reference count

  v3.1 protocols often followed the format:

  
                  foo_open()
                          if (session s exists) {
                                  s->rcnt++;
                          } else {
                                  s = xCreateSessn();
                                  fill in state;                        
                          }
                          return s;

  xOpen now automatically increments the reference count so the format should be more like:

  
                  foo_open()
                          if (session s does not exist) {
                                  s = xCreateSessn();
                                  fill in state;                        
                          }
                          return s;

• foo_close should not decrement the reference count

  In v3.1, foo_close was called whenever xClose was called, so foo_close often looked like:

  
                  foo_close()
                          if (--s->rcnt == 0) {
                                  xDestroy(s);
                          }

  In v3.2, the protocol's close function is called only when the reference count reaches zero (see the examples in the caching section.)

• xPop should not be bypassed

  Since xPop in v3.1 did nothing more than call the session's pop operation, v3.1 protocols often either called their pop routine directly or, if their pop routine was small, they absorbed this functionality into their demux routine and bypassed xPop altogether. Since xPop manipulates reference counts in v3.2, it can not be bypassed.

• xDemux should not use xOpen to create new sessions

  It is common practice for a protocol to create passive sessions (where session creation is triggered by an incoming packet rather than an xOpen) by having foo_demux call foo_open and then possibly customizing the session. There is nothing wrong with this practice, but such a protocol should invoke foo_open directly rather than using xOpen. The passively created session should have an initial reference count of 0, but xOpen would return a session with an initial reference count of 1.