2.2 Recognised Functions

A typical emodule will implement a fancy feature (or hopefully many thereof) and thence be willing to provide a lisp binding in the surface, e.g. a function, or anything similar to make use of the feature. Sounds simple, is simple: SXEmacs just asks its inbuilt crystal ball to determine which of your functions was meant to appear in the lisp engine.

Albeit tempting with respect to simplicity and comfort this behaviour is technically an effort to realise. SXEmacs therefore treats some symbols of your emodule in a special way.

Function: init

Code which is run after opening the emodule and all its requisite modules.

Usually this carries all the bindings you want to export to the lisp surface, such as macros, functions, variables and (lisp) symbols. Moreover, depending on your code this can be used to initialise private setups, such as private tables or memory blocks.

Function: reinit

Code which is run upon a reload of the emodule.

Normally this is just a deinit(); call followed by another init(); call. The reason to have a special entry point for reinitialisation is that, roughly, reinit() is not exactly just a deinit(); init(); sequence. For instance you might want to avoid to initialise certain private memory blocks again because their setup was a very expensive operation.

Function: deinit

Code which is run after closing all of a emodule’s requisites upon a unload-module request.

Usually you would unleash all your privately held resources and unbind any exported variables, functions, macros, and so forth.

Function: docs

A special function called to incorporate documentation strings for your lisp bindings.

Normally this entry point is generated automatically using the make-docfile utility.

All these function are truly optional. Their signature is actually

void(*)(emodng_t)

but you can also make them

void(*)(void)

Quick notes re emodule unloading. It seems quite natural to be able to unload stuff, at least in the perfect world. While this is still true if your emodule provides truly complementary functionality (whatever that is) it becomes a critical issue once you truly intervene or even replace internal functionality. We are NOT barring you from unloading your emodule nor are we saying you should avoid that feature but you should be aware of its dramatical consequences when done sloppily.

The best comparison we can come up with is the concept of emodules for the linux kernel. Imagine you were a emodule providing ultra fast access to, say, scsi drives and therefore had to oust the kernel’s normal handlers for those drives. Now after unloading your emodule you would reestablish the old, superseded handlers, would you not? As mentioned before, today’s system are usually not equipped with a superior intelligence being able to completely understand your concept and your mode of operation in order to automatically withdraw, or simply revert, your actions just by looking at the emodule’s code.

Ergo YOU are responsible to restore the state of the system!

It does not necessarily mean that you have to unwind completely to the exact state before you entered the scene, no, you are ‘only’ encouraged to leave a working system behind, whatever that means in the context of your emodule.

• Carefully consider if you want to unbind exported lisp variables.

  If they are not filled with special lisp objects only your emodule knows about it is definitely wise to leave them in the environment.

• Carefully consider if you want to unbind exported macros.

  After all a macro is just a piece of code which produces another piece of code under the influence of some variables passed to it, so why not simply keep that?

• Carefully consider if you want to unbind exported functions.

  This is a bit more delicate. The lisp language does not distinguish between code and data and your function could have ended up literally anywhere. Simply unbinding your functions, using UNDEFSUBR or Ffmakunbound, will possibly turn any reference to them into an error generator. This is especially annoying when your emodule’s functions were used in so frequented hooks like pre-gc-hook.

  Solution: Do not unbind your functions. Instead rebind them to something which has the same input signature but, for instance, produces an unmistakable message. Be prolific!

• Any other scenario not covered here is basically either a real auxiliary, read optionally, thing where unloading does not harm at all, or it really affects the guts of SXEmacs in which case we take it for granted that you know what you are doing anyway.