… | |
… | |
105 | recommended for this platform. This set is often smaller than the one |
105 | recommended for this platform. This set is often smaller than the one |
106 | returned by C<ev_supported_backends>, as for example kqueue is broken on |
106 | returned by C<ev_supported_backends>, as for example kqueue is broken on |
107 | most BSDs and will not be autodetected unless you explicitly request it |
107 | most BSDs and will not be autodetected unless you explicitly request it |
108 | (assuming you know what you are doing). This is the set of backends that |
108 | (assuming you know what you are doing). This is the set of backends that |
109 | libev will probe for if you specify no backends explicitly. |
109 | libev will probe for if you specify no backends explicitly. |
|
|
110 | |
|
|
111 | =item unsigned int ev_embeddable_backends () |
|
|
112 | |
|
|
113 | Returns the set of backends that are embeddable in other event loops. This |
|
|
114 | is the theoretical, all-platform, value. To find which backends |
|
|
115 | might be supported on the current system, you would need to look at |
|
|
116 | C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for |
|
|
117 | recommended ones. |
|
|
118 | |
|
|
119 | See the description of C<ev_embed> watchers for more info. |
110 | |
120 | |
111 | =item ev_set_allocator (void *(*cb)(void *ptr, long size)) |
121 | =item ev_set_allocator (void *(*cb)(void *ptr, long size)) |
112 | |
122 | |
113 | Sets the allocation function to use (the prototype is similar to the |
123 | Sets the allocation function to use (the prototype is similar to the |
114 | realloc C function, the semantics are identical). It is used to allocate |
124 | realloc C function, the semantics are identical). It is used to allocate |
… | |
… | |
923 | Configures the watcher to trigger on the given signal number (usually one |
933 | Configures the watcher to trigger on the given signal number (usually one |
924 | of the C<SIGxxx> constants). |
934 | of the C<SIGxxx> constants). |
925 | |
935 | |
926 | =back |
936 | =back |
927 | |
937 | |
|
|
938 | |
928 | =head2 C<ev_child> - wait for pid status changes |
939 | =head2 C<ev_child> - wait for pid status changes |
929 | |
940 | |
930 | Child watchers trigger when your process receives a SIGCHLD in response to |
941 | Child watchers trigger when your process receives a SIGCHLD in response to |
931 | some child status changes (most typically when a child of yours dies). |
942 | some child status changes (most typically when a child of yours dies). |
932 | |
943 | |
… | |
… | |
1006 | |
1017 | |
1007 | Prepare and check watchers are usually (but not always) used in tandem: |
1018 | Prepare and check watchers are usually (but not always) used in tandem: |
1008 | prepare watchers get invoked before the process blocks and check watchers |
1019 | prepare watchers get invoked before the process blocks and check watchers |
1009 | afterwards. |
1020 | afterwards. |
1010 | |
1021 | |
1011 | Their main purpose is to integrate other event mechanisms into libev. This |
1022 | Their main purpose is to integrate other event mechanisms into libev and |
1012 | could be used, for example, to track variable changes, implement your own |
1023 | their use is somewhat advanced. This could be used, for example, to track |
1013 | watchers, integrate net-snmp or a coroutine library and lots more. |
1024 | variable changes, implement your own watchers, integrate net-snmp or a |
|
|
1025 | coroutine library and lots more. |
1014 | |
1026 | |
1015 | This is done by examining in each prepare call which file descriptors need |
1027 | This is done by examining in each prepare call which file descriptors need |
1016 | to be watched by the other library, registering C<ev_io> watchers for |
1028 | to be watched by the other library, registering C<ev_io> watchers for |
1017 | them and starting an C<ev_timer> watcher for any timeouts (many libraries |
1029 | them and starting an C<ev_timer> watcher for any timeouts (many libraries |
1018 | provide just this functionality). Then, in the check watcher you check for |
1030 | provide just this functionality). Then, in the check watcher you check for |
… | |
… | |
1043 | =back |
1055 | =back |
1044 | |
1056 | |
1045 | Example: *TODO*. |
1057 | Example: *TODO*. |
1046 | |
1058 | |
1047 | |
1059 | |
|
|
1060 | =head2 C<ev_embed> - when one backend isn't enough |
|
|
1061 | |
|
|
1062 | This is a rather advanced watcher type that lets you embed one event loop |
|
|
1063 | into another. |
|
|
1064 | |
|
|
1065 | There are primarily two reasons you would want that: work around bugs and |
|
|
1066 | prioritise I/O. |
|
|
1067 | |
|
|
1068 | As an example for a bug workaround, the kqueue backend might only support |
|
|
1069 | sockets on some platform, so it is unusable as generic backend, but you |
|
|
1070 | still want to make use of it because you have many sockets and it scales |
|
|
1071 | so nicely. In this case, you would create a kqueue-based loop and embed it |
|
|
1072 | into your default loop (which might use e.g. poll). Overall operation will |
|
|
1073 | be a bit slower because first libev has to poll and then call kevent, but |
|
|
1074 | at least you can use both at what they are best. |
|
|
1075 | |
|
|
1076 | As for prioritising I/O: rarely you have the case where some fds have |
|
|
1077 | to be watched and handled very quickly (with low latency), and even |
|
|
1078 | priorities and idle watchers might have too much overhead. In this case |
|
|
1079 | you would put all the high priority stuff in one loop and all the rest in |
|
|
1080 | a second one, and embed the second one in the first. |
|
|
1081 | |
|
|
1082 | As long as the watcher is started it will automatically handle events. The |
|
|
1083 | callback will be invoked whenever some events have been handled. You can |
|
|
1084 | set the callback to C<0> to avoid having to specify one if you are not |
|
|
1085 | interested in that. |
|
|
1086 | |
|
|
1087 | Also, there have not currently been made special provisions for forking: |
|
|
1088 | when you fork, you not only have to call C<ev_loop_fork> on both loops, |
|
|
1089 | but you will also have to stop and restart any C<ev_embed> watchers |
|
|
1090 | yourself. |
|
|
1091 | |
|
|
1092 | Unfortunately, not all backends are embeddable, only the ones returned by |
|
|
1093 | C<ev_embeddable_backends> are, which, unfortunately, does not include any |
|
|
1094 | portable one. |
|
|
1095 | |
|
|
1096 | So when you want to use this feature you will always have to be prepared |
|
|
1097 | that you cannot get an embeddable loop. The recommended way to get around |
|
|
1098 | this is to have a separate variables for your embeddable loop, try to |
|
|
1099 | create it, and if that fails, use the normal loop for everything: |
|
|
1100 | |
|
|
1101 | struct ev_loop *loop_hi = ev_default_init (0); |
|
|
1102 | struct ev_loop *loop_lo = 0; |
|
|
1103 | struct ev_embed embed; |
|
|
1104 | |
|
|
1105 | // see if there is a chance of getting one that works |
|
|
1106 | // (remember that a flags value of 0 means autodetection) |
|
|
1107 | loop_lo = ev_embeddable_backends () & ev_recommended_backends () |
|
|
1108 | ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) |
|
|
1109 | : 0; |
|
|
1110 | |
|
|
1111 | // if we got one, then embed it, otherwise default to loop_hi |
|
|
1112 | if (loop_lo) |
|
|
1113 | { |
|
|
1114 | ev_embed_init (&embed, 0, loop_lo); |
|
|
1115 | ev_embed_start (loop_hi, &embed); |
|
|
1116 | } |
|
|
1117 | else |
|
|
1118 | loop_lo = loop_hi; |
|
|
1119 | |
|
|
1120 | =over 4 |
|
|
1121 | |
|
|
1122 | =item ev_embed_init (ev_embed *, callback, struct ev_loop *loop) |
|
|
1123 | |
|
|
1124 | =item ev_embed_set (ev_embed *, callback, struct ev_loop *loop) |
|
|
1125 | |
|
|
1126 | Configures the watcher to embed the given loop, which must be embeddable. |
|
|
1127 | |
|
|
1128 | =back |
|
|
1129 | |
|
|
1130 | |
1048 | =head1 OTHER FUNCTIONS |
1131 | =head1 OTHER FUNCTIONS |
1049 | |
1132 | |
1050 | There are some other functions of possible interest. Described. Here. Now. |
1133 | There are some other functions of possible interest. Described. Here. Now. |
1051 | |
1134 | |
1052 | =over 4 |
1135 | =over 4 |